Discover Repository State
Create a reviewable evidence snapshot before planning or implementation.
Turn contract
✓ Repository evidence was read or commands were run for every fact
✓ Facts, documentation, planned work, decisions, and inference are separated
✓ Snapshot status is frozen unless a contradiction was recorded
✓ No accepted decision or existing frozen fact was silently changed
✓ The closing → Next: block is printed last
Step 0 — Discover the project (always first)
Read the agent guide, documentation map, and any existing repository-state
ledger before collecting evidence.
Process
- Read the project guide, documentation map, and any existing
docs/workflow/REPOSITORY_STATE.md.
- Inspect repository files, tests, git state, and declared tooling. Record only
directly observed statements in Repository Facts, each with file:line or
command evidence.
- Record design records under Accepted Decisions, roadmap entries under
Planned work, and document-only claims under Documentation. Do not
copy them into facts without separate implementation evidence.
- Place reasoning under Inference and unresolved ambiguity under Open
Questions.
- If the existing snapshot is already
contradicted, preserve that status and
do not alter its unresolved contradiction; hand off to
resolve-repository-state. Otherwise, if new evidence conflicts with a
frozen fact, append a Contradiction, set snapshot status to
contradicted, and do not alter the fact. Hand off to
resolve-repository-state.
- Only if neither an existing nor a newly recorded contradiction is present,
set the snapshot status to
frozen. Commit the artifact and cite the source
revision.
Guardrails
- Discovery records repository facts and preserves decisions, planned work,
documentation, inference, questions, and contradictions in their own sections.
- The repository remains authoritative; refresh when the snapshot is stale.
- Never create implementation recommendations or silently accept decisions.
Portability
Without a slash menu, open this file and follow its process in a fresh turn.
Relationship to other skills
resolve-repository-state resolves contradictions; planners and executors
consume the frozen result.
Done when
The ledger is frozen or explicitly contradicted, and every fact carries direct
evidence.
If a contradiction was recorded:
→ Next: /resolve-repository-state — resolve the contradicted snapshot first
· provide missing evidence → rerun /discover-repository-state
Otherwise:
→ Next: /plan-feature — plan from frozen facts
· implementation-ready feature → /execute-phase
(planned is not executable: no current PLAN-REVIEW-PASS → /review-plan )
1---2name: discover-repository-state-23description: "Discover repository evidence and write a frozen Normalized Repository State. Produces verified repository evidence and keeps facts, decisions, planned work, documentation, and inference separate. It does not make recommendations or infer implementation from documentation. Triggers: \"discover repository state\", \"normalize repository state\", \"freeze repository facts\"."4---56# Discover Repository State78Create a reviewable evidence snapshot before planning or implementation.910## Turn contract1112```13✓ Repository evidence was read or commands were run for every fact14✓ Facts, documentation, planned work, decisions, and inference are separated15✓ Snapshot status is frozen unless a contradiction was recorded16✓ No accepted decision or existing frozen fact was silently changed17✓ The closing → Next: block is printed last18```1920## Step 0 — Discover the project (always first)2122Read the agent guide, documentation map, and any existing repository-state23ledger before collecting evidence.2425## Process26271. Read the project guide, documentation map, and any existing28 `docs/workflow/REPOSITORY_STATE.md`.292. Inspect repository files, tests, git state, and declared tooling. Record only30 directly observed statements in **Repository Facts**, each with file:line or31 command evidence.323. Record design records under **Accepted Decisions**, roadmap entries under33 **Planned work**, and document-only claims under **Documentation**. Do not34 copy them into facts without separate implementation evidence.354. Place reasoning under **Inference** and unresolved ambiguity under **Open36 Questions**.375. If the existing snapshot is already `contradicted`, preserve that status and38 do not alter its unresolved contradiction; hand off to39 `resolve-repository-state`. Otherwise, if new evidence conflicts with a40 frozen fact, append a **Contradiction**, set snapshot status to41 `contradicted`, and do not alter the fact. Hand off to42 `resolve-repository-state`.436. Only if neither an existing nor a newly recorded contradiction is present,44 set the snapshot status to `frozen`. Commit the artifact and cite the source45 revision.4647## Guardrails4849- Discovery records repository facts and preserves decisions, planned work,50 documentation, inference, questions, and contradictions in their own sections.51- The repository remains authoritative; refresh when the snapshot is stale.52- Never create implementation recommendations or silently accept decisions.5354## Portability5556Without a slash menu, open this file and follow its process in a fresh turn.5758## Relationship to other skills5960`resolve-repository-state` resolves contradictions; planners and executors61consume the frozen result.6263## Done when6465The ledger is frozen or explicitly contradicted, and every fact carries direct66evidence.6768If a contradiction was recorded:6970→ Next: /resolve-repository-state <contradiction-id> — resolve the contradicted snapshot first71 · provide missing evidence → rerun /discover-repository-state7273Otherwise:7475→ Next: /plan-feature <slug> — plan from frozen facts76 · implementation-ready feature → /execute-phase <NN>77 (planned is not executable: no current `PLAN-REVIEW-PASS` → /review-plan <NN>)
