Proactive Brief

Proactive Brief

Generate concise, actionable status briefs from project state and recent activity — inspired by Claude Code's KAIROS Brief Mode.

Concept

A brief is not a summary. It's a delta report: only what changed, only what matters, only what needs action. If someone read the last brief, this one should tell them everything new in 15 seconds.

Design Principles

1. Brief, not verbose — max 20 words per item. If it needs more, link to a file.
2. Delta-based — only what CHANGED since last brief. No restating known facts.
3. Actionable — every item is either informational ("X happened") or actionable ("Y needs attention by [when]")
4. 15-second rule — the whole brief should be scannable in 15 seconds. If it's longer, it's not brief.
5. Source-linked — every claim cites its source (commit, PR, issue, conversation)

Brief Template

# Brief — [Date]

## Needs Attention
- [Thing]: [1-line what + why] → [suggested action] (source: [ref])

## Changed
- [Topic]: [what changed] (source: [ref])

## Upcoming (next 48h)
- [Deadline/event]: [1-line context]

## Learned (new durable facts)
- [Fact]: [value] (source: [ref])

That's it. Four sections. If a section is empty, omit it.

Sources

What you pull from depends on your project setup. Check what's available:

Tier 1: Always available (any project)

# Recent commits
git log --since="24 hours ago" --oneline --no-merges

# Changed files
git diff --stat HEAD~5

# Open branches
git branch --sort=-committerdate | head -10

# TODO/FIXME delta
git diff HEAD~5 -- '*.ts' '*.py' '*.rs' | grep "^+" | grep -i "todo\|fixme\|hack"

Tier 2: If you have a remote

# Open PRs
gh pr list --state open --limit 10

# PR reviews needed
gh pr list --search "review-requested:@me"

# CI status
gh run list --limit 5

Tier 3: If you have integrations

• Issue tracker (Linear, Jira, GitHub Issues): Assigned tickets, status changes, blockers
• Slack/Discord: Unread mentions in project channels
• Calendar: Meetings in next 48h
• Email: Threads requiring response

Tier 4: Agent memory (if available)

• Previous session decisions not yet captured in docs
• Open questions from last conversation
• Promises made ("I'll fix X tomorrow")

Running a Brief

Manual (paste into any agent)

Generate a project brief. Follow the proactive-brief pattern:

1. Check: git log last 24h, open PRs, CI status, open issues assigned to me
2. Check: any TODO/FIXME comments added recently
3. Check: [add any integrations you use]

Format: 4 sections max (Needs Attention, Changed, Upcoming, Learned)
Rules: Max 20 words per item. Delta only — skip anything unchanged. 
       Cite sources. Omit empty sections.

Claude Code slash command

Add to .claude/commands/brief.md:

---
description: Generate a project status brief
allowed-tools: Bash(git:*), Bash(gh:*), Read, Glob, Grep
---

Generate a concise project brief following the proactive-brief pattern.

Check git log (24h), open PRs, CI status, and recent TODO additions.
Format as: Needs Attention → Changed → Upcoming → Learned.
Max 20 words per item. Delta-only. Cite sources. Omit empty sections.

Trigger with /brief in Claude Code.

Cron job (daily morning brief)

# Weekdays at 8:30am
30 8 * * 1-5 cd /path/to/project && claude -p "Generate a morning brief: git log last 24h, open PRs, CI status, assigned issues. Save to .claude/briefs/$(date +%Y-%m-%d).md. Max 20 words per item, delta-only, cite sources."

Multi-project brief

If you work across several repos, loop:

#!/bin/bash
REPOS=("~/code/api" "~/code/frontend" "~/code/infra")
BRIEF=""

for repo in "${REPOS[@]}"; do
  cd "$repo"
  BRIEF+="## $(basename $repo)\n"
  BRIEF+="$(git log --since='24 hours ago' --oneline --no-merges 2>/dev/null || echo 'No commits')\n\n"
done

echo -e "$BRIEF" | claude -p "Synthesize this multi-repo activity into a single brief. Follow proactive-brief format. Highlight cross-repo impacts."

Memory Extract Pattern

Every brief is an opportunity to capture durable knowledge. After generating the brief, check:

| Signal | Action | |---|---| | Decision made | Write to project memory / decision log | | Pattern discovered | Add to conventions / architecture docs | | Bug root cause found | Add to known issues / post-mortem | | External API behavior learned | Add to integration docs |

Rule: Only extract if the fact has signal ≥ 2 — it must have a title, a source, AND a 1-line purpose to be worth persisting.

Where to save extracted knowledge:

• .claude/memory/ — if using Claude Code's memory system
• docs/decisions/ — for decision records (ADRs)
• CLAUDE.md — for the single most important project context
• Wherever your team keeps durable docs

Examples

Morning Brief (solo developer)

# Brief — 2026-04-02

## Needs Attention
- CI: `test-auth` failing since 8pm yesterday → flaky Redis mock, see commit a3f21b

## Changed
- Merged PR #42: rate limiting middleware (3 files, +180 lines)
- New issue #51: user reports timeout on /api/export (assigned to me)

## Upcoming
- Friday: v2.5 release tag deadline

## Learned
- Redis MULTI/EXEC doesn't support WATCH inside pipelines (hit this in rate limiter)

Weekly Digest (team lead)

# Brief — W14 2026

## Needs Attention
- 2 PRs open >3 days: #38 (backend) and #41 (frontend) — need review
- Sprint velocity: 18/24 points done, 6 carry over

## Changed
- Auth service migrated to JWT (merged Monday, 12 files)
- New staging environment provisioned (infra PR #15)
- Onboarded 1 new contributor (first PR merged Thursday)

## Learned
- JWT refresh token rotation needs explicit revocation on logout (missed in spec)

Anti-Patterns

| Don't | Do | |---|---| | "The project is a web app built with..." | Skip — this is known context, not a delta | | "No changes to the database schema" | Omit — empty sections are noise | | "We should probably look into..." | Be specific: "X needs attention → do Y by [when]" | | Paragraphs of explanation | Max 20 words. Link to a file if more is needed. | | "Everything looks good" | If nothing needs attention, the brief is just Changed + Learned |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: VictorGjn
• Source: VictorGjn/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.