feature-plan-review
Skill0 starsChanged 3 months agoMITView on GitHub
Independently review a multi-repo feature's PRD.md + IMPLEMENTATION_PLAN.md before implementation. Runs mechanical cross-repo checks (missing consumers, phase order, breaking-change shape, stale map) then a fresh adversarial critique. Report only — no edits — dated, under docs/features/<slug>/plan-reviews/.
In this repository6 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- feature-buildSkill
- feature-build-step-by-stepSkill
- feature-code-reviewSkill
- feature-planSkill
- system-mapSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 18
Read PRD.md and IMPLEMENTATION_PLAN.md from the folder.
- Distinctive: line 27
Run them before spending any subagent, and hand the results to the reviewers in Step 3 as context.
- Distinctive: line 43
Check the phase sequence against the producer → consumer edges.
- Distinctive: line 47
If the PRD marks a contract change as breaking, the plan must carry it as *expand → migrate consumers → contract*.
≈ “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
You are reviewing the planning artifacts of a feature, BEFORE implementation. Feature folder: $ARGUMENTS
This skill is report-only: it does not edit the PRD or the plan, and it never
touches projects/. It writes a structured critique the user (or a re-run of
/feature-plan) can act on, and which accumulates as statistics on planning quality.
Step 1 — Load
Read PRD.md and IMPLEMENTATION_PLAN.md from the folder. Read repos.yaml,
docs/system/architecture.md, and the seam file
.claude/rules/services/<svc>.md for every service the plan claims to touch —
plus, importantly, for every service the plan does not claim to touch but which
appears as a consumer of something the plan changes.
Step 2 — Mechanical cross-repo checks (do these yourself, first)
These are cheap, deterministic, and they catch the failures a prose review misses. Run them before spending any subagent, and hand the results to the reviewers in Step 3 as context.
A. Is the map the plan rests on still true?
For each in-scope service compare the reflects: SHA in its seam file with
git -C projects/<svc> rev-parse --short HEAD. If they differ, every producer /
consumer claim below is built on sand — say so in the report header and recommend
/system-map --only <svc,...> before the plan is trusted.
B. Missing consumers — the signature multi-repo failure. For each contract the plan changes, take the owning service's seam file and list every entry under Consumers of its events and Called by. Every one of them must appear in the plan's service set. Any that does not is a candidate blocker: the feature will ship and break a repository nobody planned for.
C. Order versus dependency. Check the phase sequence against the producer → consumer edges. A phase that consumes something a later phase produces is a finding, not a detail.
D. Breaking changes are not one phase. If the PRD marks a contract change as breaking, the plan must carry it as expand → migrate consumers → contract. A single cut-over phase assumes repositories deploy atomically. They do not.
E. Required sections exist and are real. Branch name shared across repositories; test strategy (levels per service, and who owns the contract test); deploy order and rollback; the per-service status checklist. A rollback section that is not actually possible given the stated deploy order (for instance, rolling back a producer after consumers already migrated) is worse than a missing one.
F. The autonomy invariant. Flag any task that would write orchestrator artifacts into a service repository, or that changes a service's CI, hooks or settings to accommodate this orchestrator.
Step 3 — Independent critique (fresh subagents)
Spawn fresh, independent reviewer subagents so the critique is not biased by any prior planning conversation. Give them both documents, the Step 2 results, and a distinct lens each; run them in parallel and merge. Instruct them to be adversarial and concrete (cite sections), and to verify external claims — pricing, free tiers, library capabilities — rather than trust them.
Lenses:
- Requirements & decisions — completeness, clarity, testable success criteria; unresolved ambiguity; is every decision justified, or are there solutions in search of a problem?
- Library over custom — where custom code is chosen, would a maintained library be better, especially anywhere security-sensitive?
- Security & abuse — auth/authz, input validation, secrets, webhook and payment integrity, DoS, enumeration, CSRF. Include the seams: a new cross-service call is a new trust boundary.
- Cross-repo integration & operability — beyond the mechanical checks: partial deploys, version skew while phases are in flight, what a half-shipped feature does in production, observability of a flow that spans services.
- Simplification — over-engineering, YAGNI, premature complexity; what can be dropped for the stated scope. Would fewer services touched achieve the same outcome?
- Consistency & testability — PRD ↔ plan agreement, contradictions, stale references; are there seams that make this testable across repositories?
Adversarially verify each finding before it reaches the report. A plausible but wrong finding costs the reader more than a missed one, because it burns their trust in the whole report.
Step 4 — Write the report
Get today's date (date +%F). Write
docs/features/<slug>/plan-reviews/<YYYY-MM-DD>-plan-review.md:
- Verdict — is the plan ready to build? Blockers?
- Map freshness — the result of check A, up front. Everything else is conditional on it.
- Findings, grouped by severity, each with:
id,severity(blocker | high | medium | low),category(scope-gap|ordering|contract|rollback|map-stale|security|requirements|consistency|yagni|testability|invariant),location(document + section),finding,recommendation.
Be specific and actionable. A finding the reader cannot act on is noise.
Output
Print the report path and a concise summary: counts by severity, the blockers, and
whether the underlying map was fresh. Do not modify PRD.md or
IMPLEMENTATION_PLAN.md. Suggest addressing findings by re-running /feature-plan
before building.
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.

