repo-context-document · diff
git:20260718.7cc9d66 to git:20260718.206351f
12 added, 43 removed. Audit A to A.
---
name: repo-context-document
- description: Create, update, or consolidate current-state project documentation under docs/context/. Use when durable architecture, ownership, runtime, domain, flow, terminology, or engineering-practice context must be synchronized with the implemented codebase.
+ description: Create, update, or consolidate adopted current-state documentation under docs/context/. Use for durable implemented architecture, ownership, runtime, domain, flow, terminology, or engineering-practice context.
---
# Repository Context Documentation
- Maintain concise current-state documentation under `docs/context/`. Document architecture and behavior, not history or a mirrored file tree.
-
- ## Truth And Scope
-
- - Read and write only `docs/context/` unless the user explicitly expands scope.
- - Treat source code and entrypoints as primary truth, followed by active runtime configuration, tests, existing context docs, then other prose.
- - Treat context claims as working hypotheses; verify non-obvious claims against the code before relying on them.
- - Classify units by entrypoints, build targets, runtime roles, deployment, consumers, and contracts—not directory names alone.
-
- ## Context Model
-
- Use only files justified by the repository:
-
- - `summary.md`: what the system is, architecture, core flow, state, capabilities, and stack.
- - `context-map.md`: terse relative-link index with no topic content.
- - `terminology.md`: stable active terms.
- - `practices.md`: implemented or enforced conventions and invariants.
- - `apps/`, `services/`, `packages/`, `platform/`, `domains/`, and `flows/`: on-demand context for meaningful ownership and behavior units.
-
- Keep `summary.md` and `context-map.md` scannable in seconds. Keep one topic per on-demand file and split only when that improves retrieval.
+ Own the information architecture and current-state content under an adopted `docs/context/` system.
## Workflow
- 1. Detect whether the repository is a single project or a multi-unit repository.
- 2. Read all existing context files before deciding what to change.
- 3. For a clean repository, inspect manifests, entrypoints, wiring, public contracts, runtime configuration, deployment, and meaningful tests.
- 4. For a dirty repository, map changed files to affected ownership, domain, platform, and flow concepts before updating only those topics.
- 5. Create or update topic files before updating `context-map.md`.
- 6. Remove stale claims and duplicate facts.
- 7. During consolidation, merge overlapping topics, prune derivable trivia, and rebuild the index from surviving files.
- 8. Read every edited file and verify its claims against current code.
-
- ## Record
+ 1. Confirm requested topics, audience, repository adoption of `docs/context/`, dirty-worktree preservation, and authority for moves or removals.
+ 2. Read all existing context files and the minimum repository evidence needed to verify their claims.
+ 3. Classify units by entrypoints, runtime roles, deployment, consumers, state, and contracts rather than directory names.
+ 4. Create or update only justified topic files before updating the terse context index.
+ 5. Remove stale claims and duplicate facts; merge or remove files only when authorized.
+ 6. Verify every edited claim against current implementation.
- - responsibilities and ownership boundaries;
- - runtime and deployment roles;
- - meaningful contracts, state, invariants, and dependency direction;
- - end-to-end flows and cross-cutting domains;
- - proven practices that are implemented or enforced.
+ Write only under `docs/context/`. Use `docs-drift-review` for incidental change-caused drift, `docs-review` for general documentation, and `critical-journey-document` for actor-goal journeys. Link to canonical plans, specifications, runbooks, guides, and API references instead of duplicating them.
- ## Do Not Record
+ Record implemented responsibilities, ownership, runtime roles, contracts, state, invariants, dependency direction, and concise system flows. Exclude history, progress, raw file inventories, speculative design, TODO lists, duplicated instructions, and sensitive values.
- - dates, commits, history, progress, recent completions, next steps, or status reports;
- - raw file trees, function signatures, test inventories, line counts, or facts found by a trivial search;
- - speculative design, aspirational standards, or TODO lists not enforced by current behavior;
- - duplicated source documentation or repository instructions acting as a second system prompt;
- - secrets, internal credentials, or sensitive runtime values.
+ Do not impose `docs/context/` on a repository that has not adopted it without an explicit request.
- Finish with a short factual summary of context files created, updated, consolidated, or removed.
+ Finish with the context files created, updated, consolidated, or removed and the evidence used.