prd-codebase-map
Skill2 starsChanged 4 months agoMITView on GitHub
Phase 1 engg-reviews: map an open meta PRD onto a fleet of app repos using as-built status plus in-depth codegraph evidence (Graphify query/path/explain). Produces PRD-Codebase-Map artifact and PM-facing product questions (scenario, example, recommendation, why). Gate-independent — does not require impact-map-lgtm and never unlocks Gate 1 or /spec-draft. Run after /ensure-repo-graph.
In this repository22 other files it gives its agents.
- ground-specSkill
- initiative-feasibilitySkill
- learning-extractSkill
- loop-specSkill
- pre-implementSkill
- purge-initiative-artifacts-appSkill
- spec-draftSkill
- spec-implementation-planSkill
- spec-technical-reviewSkill
- ensure-repo-graphSkill
- post-product-questionsSkill
- review-product-questionsSkill
- commit-workspaceSkill
- create-board-ticketsSkill
- open-draft-prSkill
- prd-impact-mapSkill
- prd-qualitySkill
- prd-thinkSkill
- purge-initiative-artifacts-metaSkill
- review-findingsSkill
- update-documentsSkill
- validate-requirementsSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 4 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 30
Run checks in references/checks.md.
- Very specific: line 33
Prefer EXTRACTED edges. INFERRED/AMBIGUOUS alone must not justify exists.
- Very specific: line 45
Don't fix the PRD in this skill — flag and question.
- Distinctive: line 64
Read PRD fully; list capabilities / features / waves to map.
- Distinctive: line 66
Read as-built per candidate repo.
- Distinctive: line 112
Only after explicit authorization: post numbered questions linking to the map artifact.
- Very specific: line 119
Use contract: engg-reviews/v1 and stage prd-codebase-map.
- Very specific: line 127
Always gate_coupled: false.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
PRD codebase map
Ground the incoming PRD on current product reality (as-built) and in-depth codebase structure (codegraph provider) across candidate repos. Emit product questions so PM can strengthen the PRD on the meta PR.
Does not implement. Does not draft app specs. Does not open Gate 1.
NON-NEGOTIABLE
- Gate-independent. May run while meta PR is Draft and without
impact-map-lgtm. Never set/clear gate labels. Never unlock/spec-draft. - Run checks in references/checks.md. Mark SKIPPED with reason — never silently omit.
- In-depth evidence only via codegraph provider.
Prefer
EXTRACTEDedges.INFERRED/AMBIGUOUSalone must not justifyexists. - Product questions use product-question-template.md — feature language only. Engineering detail → appendix.
- As-built vs graph conflicts → product question (
conflict), not silent pick. - Cap open product questions (default 10); prioritize conflict → partial → unknown.
- Dual output: chat summary +
prd/reports/PRD-Codebase-Map-{INIT}.md. - Handoff contract
engg-reviews/v1only — see handoff-adjunct.md. - Greenfield / missing as-built + empty graph → short-circuit: PRD-ambiguity
questions only; set
grounding_depth: none; do not claim deep grounding. - Don't fix the PRD in this skill — flag and question. PE posts via
/post-product-questions; PM updates PRD with requirements skills.
Inputs
Resolve paths from references/layout-defaults.md.
- PRD — (REQUIRED)
prd/INIT-*.md+ digest + meta PR head SHA if open - Fleet graphs — (REQUIRED for deep PASS) output of
/ensure-repo-graph - As-built — per repo
docs/specification/as-built/implementation-status.md(or profile equivalent) - Impact map — (OPTIONAL) candidate repos + scope hints
- Accepted ADRs — (OPTIONAL) product-behaviour constraints only
- Prior map — (OPTIONAL) for revision increment
Process
T0 — Gather
- Read PRD fully; list capabilities / features / waves to map.
- Load fleet status (SHAs, digests). Stop if required graphs not
CURRENT. - Read as-built per candidate repo.
T1 — Understand
- Build capability inventory with PRD refs.
- Assign primary repo per capability (impact-map / catalog / evidence).
T2 — Analyze (per capability)
- Provider
querywith product-language terms. path/explainfor critical nodes; record edge confidence.- Compare to as-built row(s).
- Classify delta:
exists|partial|absent|conflict|unknown. - Queue product question if delta is
partial|conflict| high-impactunknown(and optionally confirm-drop for surprisingexists).
T3 — Plan questions
- Apply cap + priority.
- Fill scenario / example / recommendation / why / alternatives.
- Move eng paths/communities to appendix.
T4 — Execute (write artifact)
- Increment
map_revisionif prior exists. - Write references/output-template.md.
- Compute artifact digest after save.
T5 — Verify
- Re-read checks.md; every capability row has evidence or explicit unknown.
- Handoff
gate_coupled: false;next_candidates⊆ engg-reviews only.
Outcomes
| Outcome | When | next_candidates |
pass | Matrix complete; no blocking open questions required | review-product-questions and/or post-product-questions |
findings | Product questions open for PE refine / PM | review-product-questions and/or post-product-questions |
needs-input | PRD/repos/graphs incomplete | ensure-repo-graph or [] |
blocked | Provider missing and PE refused degraded mode | ensure-repo-graph |
stale | PRD digest or graph SHA mismatch mid-run | ensure-repo-graph |
failed | Write/tool failure | [] |
Meta PR comments
Only after explicit authorization: post numbered questions linking to the map artifact. Still no gate label changes.
Workflow handoff
Append the envelope from
../references/handoff-adjunct.md.
Use contract: engg-reviews/v1 and stage prd-codebase-map.
| Outcome | Next |
pass / findings | Optional /review-product-questions, then /post-product-questions |
needs-input / blocked / stale | /ensure-repo-graph then retry |
failed | Human fixes tool/write issues; retry |
Always gate_coupled: false. Never list prd-impact-acceptance, prd-merge, or
spec-draft in next_candidates. SDD Gate navigators must ignore this
contract.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

