agentleFS
delorenjdelorenj/ssbnk/.agents/skills/plan-review/SKILL.md

plan-review

Skill2 starsChanged 53 days agoMITView on GitHub

Criteria for reviewing implementation plans against quality standards

47 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use plan-execute, pr-comment and 9 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • longranger2Skill

    plan-execute

    Use when the user says "/plan-execute", "plan execute", "implement plan", or "execute plan" and provides a finalized plan file path to carry out. Claude orchestrates, Codex writes code, Claude reviews, and Codex fixes issues until the quality bar is met.

    Also in 4 projects that use this

  • BenjaminGSkill

    pr-comment

    This skill should be used when reviewing someone else's pull request and you want drafted review comments posted to GitHub — either gate / gate-wf findings (tier-marked) or pr-challenge's reviewer questions (unmarked) — each drafted through humanizer and posted as a standalone inline comment at its file:line, after one confirmation. Triggers on "post these as review comments", "comment the gate findings on the PR", "draft and post my review", "leave review comments", after a gate / gate-wf run or a pr-challenge pass on a PR you're reviewing.

    Also in 3 projects that use this

  • MicrosoftSkill

    spec-review

    Independent, multi-model review of a design or spec **before** any code is written, for the microsoft/winappcli repo. Activate when a contributor asks to "review this spec", "review my design", "review this design doc", "validate this approach", "should we build this", "spec review", "design review", or "feature review". Fans out parallel sub-agents — each doing its OWN research against the real codebase and ecosystem rather than trusting the spec — covering necessity & scope, approach & alternatives, feasibility vs reality, risks & unknowns, DX & user impact, and a different-model-family cross-check. Emits a decision-oriented recommendation (proceed / proceed-with-changes / reconsider) to stdout. This is the PRE-CODE companion to the pr-review skill (which reviews code already written); use spec-review at the design/spec stage, not on an implemented diff. Does NOT write code or edit the spec.

    Also in 3 projects that use this

  • AnthropicSkill

    office-hours

    Set up and run Claude Code office hours, including the calendar event when the champion's own calendar connector allows it. Use when a champion wants a regular time for teammates to bring problems.

    Also in 3 projects that use this

  • Hugging FaceSkill

    simplify

    Refactor code after tests pass. The "Refactor" phase of Red-Green-Refactor.

    Also in 3 projects that use this

  • AWSSkill

    retro

    Conduct a retrospective on a coding session.

    Also in 5 projects that use this

The file

We split this skill into the rules it gives an agent

10 rules. 0 are common, 9 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 40 edited versions we read keep these.

  • 9

    Distinctive

    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. Distinctive:

    When reviewing implementation plans before execution

    line 14
  2. Distinctive:

    When auditing plan quality after creation

    line 15
  3. Distinctive:

    When verifying plans meet documentation standards

    line 16
  4. Very specific:

    Do NOT re-validate format—plan_save handles structural validation

    line 134
  5. Distinctive:

    Do NOT evaluate code quality (that's code-review's job)

    line 135
  6. Distinctive:

    Do NOT execute or modify the plan during review

    line 136
  7. Distinctive:

    Do NOT skip citation verification for decisions

    line 137
  8. Distinctive:

    Do NOT accept vague goals or ambiguous tasks

    line 138
  9. Distinctive:

    Do NOT forget to note positive observations

    line 139
  10. Distinctive:

    Before completing a plan review, verify:

    line 145

“Common” is measured: kept by at least 6 in 10 of the 40 edited versions of this file we could read. “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

Plan Review

Load this skill when reviewing implementation plans (not code).

TL;DR

Systematic plan review focused on 3 quality categories: Citation Quality, Completeness, and Actionability. Structure is pre-validated by plan_save—focus on whether the plan provides actionable implementation guidance.

When to Use This Skill

  • When reviewing implementation plans before execution
  • When auditing plan quality after creation
  • When verifying plans meet documentation standards
  • As part of the plan validation workflow

Plan Review Checklist

1. Structure (Pre-validated)

Note: Saved plans are structurally validated by plan_save before storage. Format compliance (YAML frontmatter, status markers, CURRENT marker, numbering) is guaranteed. Focus your review on the quality aspects below.

2. Citation Quality

RequirementCheck
Decisions reference sourcesref:delegation-id format used
No unsubstantiated claimsArchitectural decisions cite research
Research phases show refsCompleted research tasks include citations
Citations are verifiableIDs match actual delegation outputs

Red Flags:

  • Decisions table with empty or - in Source column
  • Claims like "industry standard" or "best practice" without citation
  • Research tasks marked complete without → ref:id

3. Completeness

RequirementCheck
Goal is specificMeasurable outcome, not vague intent
Phases are logicalSequential, with clear progression
Edge cases consideredError handling, failure modes addressed
Notes section presentKey decisions and observations documented
Context & Decisions tableCaptures architectural choices with rationale

Goal Quality Examples:

  • ❌ "Improve authentication" (vague)
  • ❌ "Make it better" (unmeasurable)
  • ✅ "Add JWT authentication with refresh token support" (specific)
  • ✅ "Migrate user table to PostgreSQL with zero downtime" (measurable)

4. Actionability

RequirementCheck
Tasks are specificClear what file/component is affected
No ambiguous tasksAvoids "investigate" or "figure out" without scope
Dependencies clearSequential tasks show logical order
Implementation path obviousDeveloper can start without clarification

Actionability Examples:

  • ❌ "Set up the backend" (too vague)
  • ❌ "Make it work" (no implementation path)
  • ✅ "Create src/auth/jwt.ts with sign/verify functions" (specific file)
  • ✅ "Add bcrypt password hashing to UserService.create()" (clear scope)

Severity Classification

SeverityIconCriteriaAction Required
Critical🔴Missing citations for key decisions, no clear goal, unactionable tasksMust fix before execution
Major🟠Vague tasks, incomplete phases, missing edge case handlingShould fix
Minor🟡Missing notes, unclear dependencies, incomplete rationaleNice to fix
Nitpick🟢Style preferences, wording suggestionsOptional

Output Format

Structure your plan review as:

## Plan Review

### Files Reviewed
- `PLAN.md` (or plan content from `plan_read`)

### Overall Assessment
APPROVE | REQUEST_CHANGES | NEEDS_DISCUSSION

### Summary
2-3 sentence overview of plan quality.

### Issues

#### 🔴 Critical
- [Issue description with specific location]

#### 🟠 Major
- [Issue description with specific location]

#### 🟡 Minor
- [Issue description with specific location]

#### 🟢 Nitpick
- [Suggestion]

### Quality Assessment

| Check | Status |
|-------|--------|
| Goal is specific and measurable | PASS / FAIL |
| Citations support key decisions | PASS / FAIL |
| Tasks are actionable | PASS / FAIL |
| Edge cases addressed | PASS / FAIL |

### Positive Observations
- [What's done well - always include at least one]

What NOT to Do

  • Do NOT re-validate format—plan_save handles structural validation
  • Do NOT evaluate code quality (that's code-review's job)
  • Do NOT execute or modify the plan during review
  • Do NOT skip citation verification for decisions
  • Do NOT accept vague goals or ambiguous tasks
  • Do NOT forget to note positive observations

Adherence Checklist

Before completing a plan review, verify:

  • All 3 quality categories analyzed (Citations, Completeness, Actionability)
  • Severity assigned to each finding
  • Specific locations noted for all issues
  • Quality Assessment table completed
  • Positive observations noted
  • Output follows the standard format

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.