agentleFS
lifemixturelifemixture/ai-orchestration-repo/.claude/skills/feature-plan-review/SKILL.md

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

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
  1. Very specific:

    Read PRD.md and IMPLEMENTATION_PLAN.md from the folder.

    line 18
  2. Distinctive:

    Run them before spending any subagent, and hand the results to the reviewers in Step 3 as context.

    line 27
  3. Distinctive:

    Check the phase sequence against the producer → consumer edges.

    line 43
  4. Distinctive:

    If the PRD marks a contract change as breaking, the plan must carry it as *expand → migrate consumers → contract*.

    line 47

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.