---
name: records-keeper
description: Keep repository records ordered after meaningful code, product, architecture, or planning changes. Use when docs may be stale, when milestone work closes, when AGENTS.md or ARCHITECTURE.md may need updates, or when durable decisions need to be filed in the right repo document. Complements context-doctor, which repairs SF's .sf persistent context.
---

# Records Keeper

This skill keeps repo-local memory ordered. It updates canonical project documents, resolves stale or contradictory docs, and leaves a clear audit trail. It does not manage `.sf/` runtime state; use `context-doctor` for `.sf` persistent-context decay.

## When To Run

- After a milestone, slice, or large implementation finishes.
- After architecture, boundary, data/state, permission, or product behavior changes.
- When root `AGENTS.md`, local `AGENTS.md`, `ARCHITECTURE.md`, or docs disagree with source.
- When a user dumps planning notes that need to become durable repo knowledge.
- Before handing off a repo to autonomous agents.

## Canonical Homes

- `AGENTS.md`: short routing map and high-level agent instructions.
- Local `AGENTS.md`: directory-specific instructions; closest file wins.
- `ARCHITECTURE.md`: short operational map, boundaries, invariants, critical flows, data/state, and verification.
- `docs/product-specs/`: durable user-visible behavior.
- `docs/design-docs/`: durable design and architecture decisions.
- `docs/exec-plans/`: active/completed execution plans and tech debt.
- `docs/generated/`: generated references only.
- `docs/records/`: records audits, contradiction notes, and context-gardening outputs.
- `docs/RECORDS_KEEPER.md`: repo-specific records checklist.

## Procedure

1. Build a quick map:
   - Read root `AGENTS.md`, `ARCHITECTURE.md`, and `docs/RECORDS_KEEPER.md` if present.
   - Use Sift, `rg`, or file search to find docs and source paths touched by the change.
   - Separate observed facts from inferred intent.

2. Triage records:
   - New durable behavior goes to product specs.
   - New subsystem, boundary, invariant, critical flow, or state model goes to `ARCHITECTURE.md`.
   - Work status/evidence goes to `docs/exec-plans/`.
   - Cleanup found during work goes to the tech-debt tracker.
   - Temporary notes either become a canonical record or are removed from active flow.

3. Repair contradictions:
   - Prefer source and tests for implemented behavior.
   - Prefer product/design docs for intended behavior not yet implemented.
   - Mark superseded decisions instead of deleting useful history.
   - Cite exact files when ambiguity remains.

4. Verify:
   - Read each touched doc after editing.
   - Check links and referenced paths.
   - Ensure no two files claim canonical ownership of the same fact.
   - Record verification commands or evals in the relevant plan/quality doc.

5. Leave an audit note when non-trivial:
   - Write a dated note under `docs/records/`.
   - Include what changed, docs updated, contradictions found, and unresolved follow-up.

## Guardrails

- Keep root `AGENTS.md` short. Route; do not duplicate detailed doctrine.
- Do not rewrite large docs for style. Make minimal records repairs.
- Do not edit protected human-authored strategy docs destructively without a clear reason.
- Do not move generated material into hand-maintained docs.
- If `.sf/CODEBASE.md`, `.sf/KNOWLEDGE.md`, memories, or `.sf/DECISIONS.md` are stale, switch to `context-doctor`.

