| name | capture-knowledge |
| description | Capture durable, project-specific learnings from the work just done into the knowledge/ base — gotchas, implementation quirks, tooling traps, SwiftData/CloudKit & TMDb-mapping surprises, things looked up or web-searched, and design decisions (as ADRs). Use before opening a PR (it runs automatically in /deliver), or any time you've learned something worth remembering. Records only non-obvious, reusable facts; skips anything already in the repo, CLAUDE.md, or git history. |
Capture Knowledge
Fold what you just learned into the committed knowledge base at knowledge/, so a
future session (or contributor) doesn't have to re-learn or re-discover it. Run
this before a PR — in /deliver it runs as the last step before /pr, so the
notes land in the same PR as the change. The knowledge/ files are plain Markdown
(no code-review or CI gate on them), so readability is on you.
What to capture (be selective)
Record only durable, project-specific, non-obvious facts — the test is "would
a future me waste time without this?":
- Gotchas / quirks →
knowledge/gotchas.md — a trap you hit, a tooling
surprise, a SwiftData/CloudKit quirk, a TMDb-mapping surprise (a
nullable/absent field, an unexpected library shape), anything that needed a
web search or doc lookup to resolve.
- Design decisions → a new ADR in
knowledge/decisions/ (next number),
using decisions/0000-template.md. Any non-obvious choice and its rationale —
why this approach over the alternatives (an MVVM boundary, a factory/DI wiring
call, a SwiftData/CloudKit modelling decision, a Statsig gating choice).
There is no live-API notes file. Popcorn consumes TMDb through the TMDb Swift
package, not raw HTTP, so API-shape quirks go in gotchas.md — route to gotchas
or an ADR only.
What NOT to capture
Mirror the discipline of a good memory — don't record:
- Anything already in the code,
CLAUDE.md, docs/*.md, the DocC docs, or git
history.
- Facts that only mattered to this one task and won't recur.
- Restatements of the obvious. If asked to record something obvious, capture the
non-obvious part (what surprised you) or skip it.
Quality over volume: a few high-signal entries beat a long dump. Capturing
nothing is a valid outcome — don't manufacture entries to look productive.
This skill writes gotchas.md and ADRs only. It does not touch
delivery-retros.md or skill-improvement-log.md — those are written by
/deliver's Phase 8 retrospective and Phase 11 wrap-up, not here.
Steps
- Start from the candidates list, if one exists. If the caller passed a
knowledge-candidates list as the argument (
$ARGUMENTS below — /deliver
pastes its ledger list here), use that as your input — that's the reliable
source, jotted while the learnings were fresh, and it reaches you intact even
if the caller's context was compacted. Otherwise, reconstruct candidates by
reviewing the work just done — the diff, the dead-ends, the things you looked
up, the decisions you made.
- Filter against "What NOT to capture". Drop the rest.
- Check for duplicates — skim the relevant
knowledge/ file; update an
existing entry rather than adding a near-duplicate.
- Write each entry in the right file:
- Gotchas: a short dated subsection (
### <title>), newest at the top, under
the right heading. Date it with today's date.
- Decisions: copy
decisions/0000-template.md to
decisions/NNNN-<kebab-title>.md (next free number), fill in Status / Date /
Deciders / Context / Decision / Consequences / Alternatives. Cross-link
related ADRs.
- Retire what's no longer true. The base is a cache of current truths, not
an archive (git history is the archive — see
knowledge/README.md → Maintenance &
retention, the authority on retention). While you're in gotchas.md, scan the
neighbouring entries and delete any now obsolete — an upstream bug fixed, a
pinned dependency version lifted, the code removed, a quirk that no longer
reproduces. The file should describe the present, not narrate the past. ADRs are
immutable: supersede an outdated one with a new ADR that links back; never
edit an Accepted ADR in place.
- Keep it tidy by hand — blank lines around headings/lists/code fences, a
language on every fence, one
# H1 per file. knowledge/ is not under any
markdown lint or CI gate, so there's nothing to catch sloppiness for you —
readability is on you. Aim for ~80-col prose; long URLs are fine.
- Update
knowledge/README.md only if you added a new file or category (the
per-entry index inside each file is enough otherwise).
Return
Report concisely what you captured: each entry → which file (and ADR number for
decisions), and note anything you deliberately skipped as not durable. If nothing
met the bar, say so plainly — capturing nothing is a valid outcome.
Arguments: $ARGUMENTS
