| name | brag |
| description | Append a one-line accomplishment to docs/BRAG.md, or summarize entries from a time window. Use when the user says "log this", "add to my brag doc", "record this", after shipping something meaningful, or when prepping for a 1:1, self-review, or promo packet. Subcommands via first argument; `add` is default. Also invoked automatically by the Stop hook at the end of substantive turns (see .claude/hooks/brag-log.sh). |
| when_to_use | User explicitly logs an accomplishment OR asks to see what they've done recently OR is preparing for a performance review. |
| argument-hint | add|summarize [description or time window like 'last-month'] |
| allowed-tools | Read Edit Write Bash(date:*) Bash(git log:*) |
Brag document
From Ch. 6: "Keep a brag document. Nobody else is tracking your wins for
you, and by review time the details have evaporated."
The file lives at docs/BRAG.md. Entries are dated, tagged by impact
level, and brief — aim for two lines each.
Subcommands
add (default)
- Parse the description from
$ARGUMENTS. If the first token is
literally add, strip it.
- Fetch today's date (
date +%Y-%m-%d) and, if in a git repo, the short
SHA of HEAD.
- Classify the impact level (from Ch. 6, mapped to Ch. 1's spectrum):
- Task — a shipped piece of work (one feature, one bugfix, one doc)
- Project — a multi-week effort you drove
- Initiative — cross-team or strategic, affects how others work
- Write the entry using the template below. Prepend it under the
current month's heading; create the heading if absent.
- Print a one-line confirmation: "Logged: <summary> (impact:
<level>)". Do not dump the whole brag doc.
summarize [window]
Valid windows: last-week, last-month, last-quarter, this-year, or
an explicit ISO date range like 2026-01-01..2026-03-31.
- Read
docs/BRAG.md. Parse entries by date.
- Produce a digest with three sections:
- Highlights — up to 5 entries (prefer
Initiative > Project >
Task), paraphrased into 1-line impact statements (STAR-ish: what
changed, for whom, with what result).
- By the numbers — count of entries per impact level and any
metric you can extract from entry bodies (perf %, cost saved, users
onboarded).
- Theme — one sentence naming the pattern across the period
("Deepened expertise in billing", "Unblocked platform team
twice").
- Print the digest. Do not modify the file.
Entry template
## 2026-03
### <Short title> — <Task | Project | Initiative>
- **Date / Ref:** 2026-03-14 · <SHA or PR/issue link>
- **What:** <one line, the visible outcome>
- **Impact:** <one line, who benefited and how — use numbers when you have
them (users, latency, cost, cycle-time)>
- **My role:** <one line: lead, contributor, reviewer, mentor, designer>
Guardrails (Ch. 6)
- No ego-writing. "Heroically shipped", "saved the team" — rewrite
to a factual outcome ("shipped X; team's deploy time dropped from Y to
Z"). The audience for this doc is a future you, a manager, or a promo
committee — it needs to be credible.
- Include partial work. A spike that proved an approach wrong is a
win. Log it as a Task with impact "avoided <cost of wrong path>".
- Cite numbers when they exist. "~20% faster" is fine; "faster"
without a number is weak.
- Don't auto-embellish. When the Stop hook feeds an entry, it is the
user's words + a commit reference. Do not invent impact statements that
aren't supported by the diff or the conversation.
