capturing-memory

name

capturing-memory

description

Invoke this skill whenever any of the following occurs during work: (1) you discover or confirm a durable fact, constraint, invariant, or “how we do X here” pattern; (2) you create a new workflow/checklist that will be reused; (3) you resolve a recurring confusion (“where is the source of truth?”); (4) you make a decision that is not an ADR/SPEC but would prevent rework; (5) you detect a sharp edge, footgun, or non-obvious dependency that future agents will hit. Do NOT rely on conversational context to persist. When the information would save ≥10 minutes for a future agent, write a memory record immediately.

Procedure:

1. Choose the correct memory_type (use the narrowest type that fits):

   • fact: atomic, checkable truth (defaults, limits, invariants)
   • pattern: repeatable recipe / command sequence / workflow
   • system: high-level subsystem map + pointers (NOT a spec)
   • concept: stable mental model, terminology, or taxonomy
   • signpost: “start here” navigation pointer set
   • thread: short-lived, context-dependent working set (expires quickly) Use spec-driver create memory NAME --type TYPE and include --summary and --tag early.

2. Create the record:

   • Command: spec-driver create memory "..." --type <concept|fact|pattern|signpost|system|thread> [--summary "..."] [--tag ...]
   • Default to lean frontmatter. Keep only fields that improve retrieval/ranking/review now; avoid metadata that can be inferred or generated later.
   • Practical baseline:
     • Keep: id, name, kind, status, memory_type, updated (and usually tags, summary).
     • Add when useful: scope, priority, verified, review_by, provenance.sources.
     • Usually omit: audience: [human, agent] (default), created (low value vs updated/verified), and visibility unless you are intentionally wiring pre-read/write hook surfacing.
   • If the content is risky or easy to drift, add/ensure frontmatter: provenance.sources (code/doc/adr/spec/commit refs), verified (today), and review_by (short horizon for volatile items).

3. Scope it so it will be findable:

   • Add scope.paths for exact file(s) when the memory applies to specific files (strongest match).
   • Add scope.globs for subsystem-level relevance (e.g., src/auth/**).
   • Add scope.commands if it is tied to a command flow (token-prefix semantics).
   • Add tags in tags for stable categorization; do not overload tags as scope.

4. Keep the body short and executable:

   • Put the “do X” steps in bullets with exact command snippets.
   • Use [[artifact-id]] in prose to reference related artifacts (e.g., [[ADR-012]], [[mem.pattern.cli.skinny]]). These are cheaper than manual relations entries. Reserve relations for lifecycle semantics (supersedes, depends_on).
   • Treat links.out as derived metadata: do not hand-author it; generate only when a consumer needs resolved links.
   • For system/concept/signpost, prefer pointers to authoritative artifacts over restating them.
   • If the item would become an ADR/SPEC/other artifact, STOP and link to the proper artifact instead; memory should remain a pointer/recipe layer.

5. Immediately sanity-check surfaceability:

   • Run spec-driver list memories --type <type> --path ... --command ... --match-tag ... to confirm it appears under the intended context.

6. Resolve inline links (if body contains [[...]]):

   • spec-driver resolve links — populates links.out from body tokens.
   • Prefer running this on-demand (or in bulk maintenance passes) rather than committing large generated link blocks by default.