Know my repo

Know My Repo

Day one on a codebase you have never seen. No docs, no notes, no memory — just code. This skill turns that into a knowledge set a future agent can load and be productive immediately, built the only honest way: by reading the code, running the commands, and citing everything.

Sibling skills: this one creates knowledge where there is none. If rotten knowledge files already exist, recommend clean-slate (reset with backup gate) instead of writing competing docs next to them.

The Prime Directive (family rule)

No claim without evidence. Every statement in the generated docs carries a file:line citation, a command you actually ran, or an explicit UNVERIFIED tag. A convention is only a convention with two or more examples and no counterexample — otherwise report it as an inconsistency.

Progress checklist

Copy this into your response and check items off:

Know My Repo Progress:
- [ ] Step 1: Recon — stack, size, knowledge files checked, Newcomer Questions written
- [ ] Step 2: Deep read — structure, data flow, wiring, git trajectory, ops (parallel)
- [ ] Step 3: Conventions — extracted with 2+ examples each; inconsistencies listed
- [ ] Step 4: Commands — build/test/lint verified by running them
- [ ] Step 5: Exemplar trace — one real feature followed end to end
- [ ] Step 6: Write — Findings Brief confirmed, then AGENTS.md + docs/ARCHITECTURE.md, fully cited
- [ ] Step 7: Cold-start test — docs answer the Newcomer Questions; mechanical checks pass
- [ ] Step 8: Report

Step 1 — Recon

• Resolve the target: if a [project-root] argument was given, treat that path as the repo root for every step below; otherwise use the current working directory. State which one you used in the final report.
• Detect stack and size: manifests (package.json, composer.json, go.mod, …), lockfiles, top-level layout, file count.
• Check for existing knowledge files (CLAUDE.md, AGENTS.md, .cursorrules, docs/ARCHITECTURE.md, …):
  • None or trivial (< ~20 meaningful lines): proceed; merge the trivial content in later.
  • Substantial: stop and ask ONE question — update what exists, or reset via clean-slate? Recommended answer included. Never write competing docs beside living ones.
• Write the Newcomer Questions — a numbered list (typically 8–15) of what a productive newcomer must be able to answer. Always include: where does feature work happen, how do I run the tests, how is a feature added end to end, how does this deploy and run in production, and what will bite me first. Add repo-specific questions as recon reveals them. Steps 2–5 exist to answer this list: findings cite the question number they answer, questions discovered mid-read are appended, and the deep read is complete when every question is answered with evidence or tagged UNVERIFIED — not when every file has been read.

Preflight: if the repo is empty or contains only scaffolding (no meaningful code), note it and proceed with minimal docs reflecting that state.

Step 2 — Deep read

Read the repo like deep-plan Phase 1. If exploration subagents are available, fan out in parallel with distinct scopes; otherwise cover the same scopes sequentially — see references/exploration-guide.md:

1. Structure & entry points
2. Data flow (write path AND read path, end to end)
3. Wiring (DI, config, registration, env)
4. Tests & quality gates
5. Git trajectory (~30 commits: what is the team building toward?)
6. Operational reality (deploy pipeline, environments, background jobs, data scale — docs that ignore how the thing ships are incomplete)

Classify components works / half-wired / dead, each with a proving file path. Merge subagent reports and spot-check surprising claims yourself before accepting them.

Step 3 — Extract conventions

Conventions are what make generated code look native. Extract them with evidence per references/conventions-guide.md: naming, module boundaries, error handling, state, styling, test patterns. Rule: 2+ examples = convention; 1 example = observation; conflicting examples = inconsistency (report it, do not pick a winner silently).

Step 4 — Verify the commands

Find the build / test / lint / run commands (manifests, CI config, Makefile) and run the safe ones (read-only: build, test, lint — not deploy, not migrate). Record real results: a test suite that fails on a clean checkout is a first-class finding, not an embarrassment to hide. Commands you could not run are listed as UNVERIFIED with the reason AND what would unblock a real run (missing env var, service, credentials) — no unknown sits silently behind a bare tag.

Step 5 — Exemplar trace

The single most useful artifact for a newcomer: pick ONE representative, recently-touched feature and trace it end to end — route/entry → handler → service → storage → output/render, naming every file on the path. This becomes the "How to add a feature here" section: the repo's own pattern, proven by its own code, not a generic tutorial.

Step 6 — Write the knowledge set

Findings Brief Gate — before writing a single file, present a compact brief in chat: stack and architecture in a sentence or two, the target file names (AGENTS.md vs CLAUDE.md), the verified command results, and every inconsistency with a recommended resolution. 10–20 lines total; this is the brief, not the docs. Ask for confirmation once. A correction here costs one message; after Step 6 it costs a rewrite. If the user cannot respond (headless/CI run), proceed — creating files is reversible and nothing is deleted — but leave every inconsistency dual-cited and unresolved, and tag any user-dependent choice UNCONFIRMED in the docs.

Then follow references/knowledge-templates.md:

• AGENTS.md — ground rules from real conventions, verified commands, observed gotchas. Under 150 lines. (Write to CLAUDE.md/AGENT.md instead if the repo's tooling expects that name.)
• docs/ARCHITECTURE.md — overview, component table with status, data flow, the exemplar trace, inconsistencies and sharp edges.

Do NOT generate a ROADMAP.md — direction is the user's call, not the code's. If half-wired components suggest unfinished intent, list them in the report and offer deep-plan as the follow-up.

Step 7 — Cold-start test

Re-read only the files you just wrote, as if you were a fresh agent, and answer the numbered Newcomer Questions from Step 1 using the docs alone. Every question you cannot answer from the docs is a gap — fix it, or list it under Unverified with what would confirm it, before presenting.

Then run the mechanical checks — these are commands, not judgment calls, and all MUST pass before presenting:

1. wc -l AGENTS.md → 150 or less. Over budget = cut informative lines until it passes; do not present and apologize.
2. Repo metadata is evidence, not inference: any remote/hosting/author line in the docs must match git remote -v / git config output exactly. Never construct a GitHub/GitLab URL from the repo's name — that is fabrication. No remote configured = say so.
3. Every "convention" line cites 2+ locations; anything with one citation is relabeled observation — grep your own output for the word "convention" and check each.
4. Proportionality: docs should not dwarf the code (a 500-line app does not need 600 lines of architecture doc) — cut repetition, keep facts.
5. Walk the Newcomer Questions by number: every question is either answered in the generated docs or listed in the Unverified section. A silently dropped question fails the gate.
6. Every Gotcha line carries a file:line citation or an "observed running <command>" note. A gotcha that could be pasted into any repo's docs unchanged is deleted, not kept as filler.

Step 8 — Report

• The completed progress checklist from the top of this skill — checked off honestly; an unchecked item with a reason beats a falsely checked one.
• Created: the files, one line each.
• Key findings: stack, architecture in one paragraph, top 3 sharp edges.
• Inconsistencies: conventions that conflict (the team may want to pick one).
• UNVERIFIED: what you could not confirm and why.
• Suggested follow-up: half-wired components worth a deep-plan run.

When things go wrong

Situation	Response
Repo is empty or only scaffolding	Complete with minimal docs noting current state; AGENTS.md states "scaffolding only, no features yet"
Commands fail on clean checkout (Step 4)	Record honest failure with output; this is a first-class finding, not a failure of the skill
No git history available	Skip git trajectory (Step 2 Scope 5); note UNVERIFIED: no git history in ARCHITECTURE.md; rely on file timestamps
User unavailable at Findings Brief Gate (headless)	Proceed with file creation (reversible); leave inconsistencies dual-cited and unresolved; tag choices UNCONFIRMED
Cold-start test fails (Step 7) — docs don't answer Newcomer Questions	Fix the gaps or list them under Unverified with what would confirm them; do not present until gate passes