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

1. Read the project guide, documentation map, and any existing

docs/workflow/REPOSITORY_STATE.md.

1. Inspect repository files, tests, git state, and declared tooling. Record only

directly observed statements in Repository Facts, each with file:line or command evidence.

1. 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.

1. Place reasoning under Inference and unresolved ambiguity under **Open

Questions**.

1. 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.

1. 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 <contradiction-id> — resolve the contradicted snapshot first · provide missing evidence → rerun /discover-repository-state

Otherwise:

→ Next: /plan-feature <slug> — plan from frozen facts · implementation-ready feature → /execute-phase <NN> (planned is not executable: no current PLAN-REVIEW-PASS → /review-plan <NN>)