| name | annotate |
| description | Persist a gotcha, caveat, or learned lesson about an API, library, or project behavior into the annotations memory. Call this whenever you discover unexpected behavior, non-obvious workarounds, or version-specific bugs — so the next agent session remembers what was learned. |
| argument-hint | <service-or-library> <what-you-discovered> |
| user-invocable | true |
| allowed-tools | Read, Edit, Bash |
| effort | 1 |
| when_to_use | When you encounter: unexpected API behavior, undocumented caveats, version incompatibilities, rate limit quirks, authentication edge cases, or any non-obvious workaround that took time to discover |
/annotate — Persist a Learned Lesson
You are adding a persistent annotation to the project's learned knowledge base.
Annotations survive across sessions and auto-load when working with relevant services.
Arguments: $ARGUMENTS — format: <service> <description of gotcha/caveat>
Phase 1 — Parse the Annotation
Extract from $ARGUMENTS:
- Service/Library: The specific service, library, or area (e.g.,
stripe, next.js, postgresql)
- Annotation text: The gotcha, caveat, or learned lesson
If $ARGUMENTS is empty or unclear, ask:
"What service/library does this apply to, and what did you discover?"
Phase 2 — Format the Entry
Format the annotation as:
- [YYYY-MM-DD] <clear, specific description of the issue> — <workaround if applicable>
Good example:
- [2026-04-07] Stripe webhook signature verification requires raw body buffer, not parsed JSON.
Pass rawBody to stripe.webhooks.constructEvent() instead of req.body
Bad example:
- Stripe webhooks broken ← too vague, no date, no solution
Apply this quality check before writing:
- ✅ Specific enough to be actionable without additional research?
- ✅ Includes the date?
- ✅ Includes workaround if one exists?
- ✅ Would a new developer understand this without context?
Phase 3 — Find or Create the Section
Read .claude/memory/annotations.md.
- Find the existing section that matches the service (case-insensitive)
- If no matching section exists, create one:
## <Service Name>
- [YYYY-MM-DD] <your annotation>
- If the section exists and has
*(no annotations yet)*, replace that line with the entry.
- If the section exists with entries, append the new entry below the last one.
Phase 4 — Write and Confirm
Edit .claude/memory/annotations.md with the new entry.
Then confirm:
✅ Annotation saved to .claude/memory/annotations.md
Service: <service>
Entry: [YYYY-MM-DD] <annotation text>
This will auto-load in future sessions when working with <service>.
Annotation Quality Rules
- Never write vague entries like "be careful with X" — always explain WHY
- Always include the date (use current date: 2026-04-07)
- Always include the workaround if you found one
- Prefer short entries (1-2 lines) — link to docs if more context needed
- Mark if issue is version-specific:
(affects v2.x, fixed in v3.0)
- Group related gotchas under the same service header
When Agents Should Use This Automatically
You do NOT need to wait for /annotate to be called explicitly.
Proactively add annotations when you:
- Spend more than 10 minutes debugging an unexpected API or library behavior
- Find that official docs are wrong, incomplete, or misleading
- Discover a version incompatibility not mentioned in release notes
- Work around a bug with a non-obvious solution
- Find that a library's "default" behavior causes problems in this project's setup
Pattern from Context Hub: The value compounds over time.
Each annotation means the NEXT session starts smarter — not from zero.
