📚 Refine plan and code review criteria

Make review criteria proportional to risk and project conventions.
Keep code reviews read-only, use existing test evidence and stable IDs.

AI-assisted-by: gpt-6.1-terra
This commit is contained in:
Andrey Antukh 2026-11-18 18:59:17 +00:00
parent 14a623da08
commit 7d5fef711c
3 changed files with 174 additions and 467 deletions

View File

@ -1,174 +1,95 @@
---
name: code-review-criteria
description: Code review criteria — the five review axes, core principles, severity format, and verdict for reviewing code changes. Loaded by the reviewer subagent of the review-code flow. Not a user-facing flow — to review code, use the review-code flow.
description: Code review criteria for correctness, clarity, architecture, security and performance. Loaded by the review-code subagent.
---
# Code Review Criteria and Quality
# Code Review Criteria
## Overview
Assess whether the change improves the codebase and is safe to merge. Review
the diff in context, its intent and relevant tests. Follow project conventions
and module memories. Do not block on personal preferences or invent problems.
Apply each axis in proportion to the change and its risks.
Multi-dimensional code review with quality gates. Every change gets reviewed before merge — no exceptions. Review covers five axes: correctness, readability, architecture, security, and performance.
Follow `review-code` for delegation and its read-only contract. Never run tests,
builds, linters or other state-changing checks during a review or follow-up.
Inspect prior test results or CI evidence when available. Identify their source
and scope; if evidence is missing, stale or inaccessible, say what is
unverified. Never claim a suite passed without evidence.
**The approval standard:** Approve a change when it definitely improves overall code health, even if it isn't perfect. Perfect code doesn't exist — the goal is continuous improvement. Don't block a change because it isn't exactly how you would have written it. If it improves the codebase and follows the project's conventions, approve it.
## Review axes
## When to Use
### Correctness and tests
- The reviewer subagent of the `review-code` flow loads this skill to perform the review of a code change.
- To review code, always go through the `review-code` flow — never load this skill directly for that. This is the criteria reference, not the flow.
Check requirements, relevant boundaries, error paths, concurrency and state.
Use the module's contracts to decide where validation belongs; do not demand
redundant guards inside functions with established preconditions. Check that
new functionality has tests covering its behavior and important failure
cases, using the appropriate layer and project testing guidance. Missing
required tests are findings; documentation-only changes need not add tests.
Do not infer that a test failed before a fix without evidence.
## Core Principles
### Readability and simplicity
These principles underpin every axis. When in doubt, default to them.
Check names, control flow and maintainability against existing conventions.
Flag duplication when it creates a concrete risk of drift or maintenance
cost, not merely because code appears more than once. In tests, prefer
self-contained, readable cases even when they repeat setup. Suggest the
simplest remedy that preserves behavior.
- **DRY (Don't Repeat Yourself):** Every piece of knowledge has one authoritative representation. Flag duplicated logic as a required change — it is not "just similar", it is drift that will diverge.
- **KISS (Keep It Simple, Stupid):** The simplest solution that works is the best solution. Complexity must earn its place: if it needs more than a sentence to explain, push for simplification before merge.
- **YAGNI (You Aren't Gonna Need It):** No abstractions, hooks or generalizations for hypothetical future use cases. Generalize on the third occurrence, not the first.
- **Don't invent problems:** Every finding must be a real risk, a real readability barrier, or a real architectural concern — not a hypothetical or a stylistic preference disguised as a problem.
### Architecture and compatibility
## The Five-Axis Review
Check module boundaries, existing abstractions, contracts and unnecessary
complexity. Review surrounding code when needed to understand the change.
Do not label a compatibility shim dead code without checking its purpose.
For file formats or data model changes, consult the relevant compatibility,
migration and feature memories; for Clojure, logging and translations, read
the corresponding guidance when relevant.
Every review evaluates code across these dimensions.
### Security
### 1. Correctness
Evaluate relevant input boundaries, authorization, secrets, data handling and
external integrations. Consult project security guidance for the affected
technology; do not assume a generic framework or tool applies to this module.
Does the code do what it claims to do?
### Performance
- Does it match the spec or task requirements?
- Are edge cases handled (null, empty, boundary values)?
- Are error paths handled (not just the happy path)?
- Do the tests cover the changed behavior, including its edge cases?
- Are there off-by-one errors, race conditions, or state inconsistencies?
Assess relevant hot paths, resource bounds, data access and scaling. Explain
the workload or conditions in which a problem matters; do not flag speculative
optimizations without a concrete risk.
### 2. Readability & Simplicity
## Scope and dependencies
Can another engineer (or agent) understand this code without the author explaining it?
Review relevant generated files or lockfile changes when they affect the
contract, dependencies or security; do not skip a lockfile-only dependency
change. Check dependency changes against available changelogs, project tools
and relevant lockfile diffs. Treat size as a signal to assess reviewability,
not an automatic finding. Identify unrelated work in the target diff when it
materially impedes review; do not review unrelated working-tree changes.
- Are names descriptive and consistent with project conventions? (No `temp`, `data`, `result` without context)
- Is the control flow straightforward (avoid nested ternaries, deep callbacks)?
- Are there "clever" tricks that should be simplified? Could this be done in fewer lines? (1000 lines where 100 suffice is a failure)
- Is a new conditional bolted onto an unrelated flow? Push the logic into its own helper, state, or policy.
- Do repeated conditionals on the same shape appear? They signal a missing model or dispatcher.
- Are there dead code artifacts: no-op variables, backwards-compat shims, or `// removed` comments?
## Findings and verdict
### 3. Architecture
Assign each finding a stable ID (`F1`, `F2`, …), independent of severity.
Never renumber it within the review or follow-up; severity may change as
evidence changes. New findings receive unused IDs.
Does the change fit the system's design?
For each finding state severity, file and location, concrete circumstances,
impact, remedy and the tests needed to verify it; explain when no new test is
needed. If a consequential decision requires user input, give the real options,
consequences and recommendation within that finding, without pausing to ask.
- Does it follow existing patterns or introduce a new one? If new, is it justified?
- Does it keep clean module boundaries, with dependencies flowing the right way (no cycles)?
- Is the abstraction level appropriate (not over-engineered, not too coupled)?
- Is there existing code that already does this? Reuse the canonical helper instead of a near-duplicate, and collapse branches that do nearly the same thing.
- Is feature-specific logic leaking into a shared or general-purpose module?
- Are type boundaries explicit? Question gratuitous `any`/`unknown`/optional/casts and silent fallbacks.
- Does the change reduce complexity or relocate it? Count the concepts a reader must hold: prefer the restructuring that makes whole branches disappear, and deleting an abstraction over polishing it.
- **Give the remedy, not only the problem:** replace conditionals with dispatchers, separate orchestration from business logic, extract helpers, split large files. Prefer the remedy that removes moving pieces over one that spreads the same complexity around.
- **Critical:** security incident, data loss or comparably severe breakage;
blocks merge.
- **High:** a significant defect or missing required test; must be addressed.
- **Medium:** a substantive issue worth fixing but not a merge blocker.
- **Low / Suggestion:** an optional improvement with a concrete benefit.
### 4. Security
Base severity on impact and project requirements. Missing tests required for
new functionality must be addressed; do not invent a test requirement for
changes where none applies.
For detailed security guidance, see `security-and-hardening`.
- Is user input validated and sanitized?
- Are secrets kept out of code, logs, and version control?
- Is authentication/authorization checked where needed?
- Are SQL queries parameterized (no string concatenation)?
- Are outputs encoded to prevent XSS?
- Are dependencies from trusted sources with no known vulnerabilities?
- Is data from external sources (APIs, logs, user content, config files) treated as untrusted?
### 5. Performance
- Any N+1 query patterns?
- Any unbounded loops or unconstrained data fetching?
- Any synchronous operations that should be async?
- Any unnecessary re-renders in UI components?
- Any missing pagination on list endpoints?
- Any large objects created in hot paths?
## Review Process
1. **Understand the intent** — What is this change trying to accomplish? What spec or task does it implement?
2. **Review tests first** — Tests reveal intent and coverage. Do they test behavior, not implementation details? Are edge cases covered?
3. **Review the implementation** — Walk through each file with the five axes in mind.
4. **Categorize findings** — Label every comment with its severity:
| Prefix | Meaning | Author Action |
|--------|---------|---------------|
| **Critical:** | Blocks merge | Security vulnerability, data loss, broken functionality |
| **High:** | Required change | Must address before merge |
| **Medium:** | Should fix | Strongly recommended, not a blocker |
| **Low:** | Minor, optional | Author may ignore — formatting, style preferences |
| **Suggestion:** | Worth considering | Not required, but improves the code |
**Finding IDs.** Assign every finding a stable identifier by severity class: `R1`, `R2`, … for required findings (Critical, High), `M1`, `M2`, … for minor findings (Medium, Low), and `S1`, `S2`, … for suggestions. Number within each class in review order. Use the ID everywhere the finding is mentioned — in section headers, in the verdict, in follow-up discussion. Never renumber within a review. Example: `**R2** — `app/validate.cljs:42` — duplicate branch logic…`.
For each finding, describe the circumstances under which it could fail: specific inputs, load conditions, timing, or user actions that trigger the problem. "This crashes when input is null" is actionable; "this might crash" is not.
For each finding, propose a concrete remedy and the tests needed to verify it. If a decision requires user input, state the real options, their consequences, and your recommendation within that finding. Do not ask the user to decide during the review, and do not ask about implementation details the code can settle.
Lead with what matters: correctness and security first, then structural issues, then everything else. A few high-conviction comments beat a long list.
5. **Check the evidence, do not re-run it** — Which tests cover the change? What did the author run, and what did CI report? Never re-run the full suite or a build yourself: the author's run and CI already cover that, and repeating it only lengthens the review. Run at most the single test file that settles a specific doubt. When no checks have been run at all (a change you did not see tested), run the module's checks before the verdict.
## Change Sizing
Small, focused changes are easier to review, faster to merge, and safer to deploy. Flag the size when a diff exceeds ~300 lines, or when it grows a file past ~1000 total lines, and name the remedy: split it, and separate refactoring from feature work. This is a finding about the change, not work to do inside the review.
## Dependencies
Before accepting a new dependency: does the existing stack already solve it, how large is the bundle impact, is it maintained, does `npm audit` report anything, is the license compatible. Prefer the standard library and existing utilities — every dependency is a liability.
For upgrades: read the changelog, not just the version number; one dependency per change; a green suite before and after; review the lockfile diff and never hand-edit it. Supply-chain triage follows `security-and-hardening`.
## Review Output
Structure every review using this format:
### Summary
Briefly explain what the code does and give an overall assessment.
### Critical and High-Priority Issues
List problems that could cause security incidents, data loss, crashes, incorrect behavior, or major performance degradation. Each finding gets its unique ID (`R1`, `R2`, …). For each: state the severity, identify the file/function/code section, explain why it's a problem, describe failure circumstances, and provide a concrete improvement with corrected code when useful. Include the tests needed and any user decision, options and recommendation in the finding itself.
### Other Findings
List medium- and low-priority issues, including maintainability and design concerns. Use `M1`, `M2`, … for Medium/Low and `S1`, `S2`, … for Suggestions. Apply the same remedy, test and decision guidance to each finding; say when no new test is needed and why.
### Suggested Refactoring
Provide focused code changes or revised snippets. Preserve existing behavior unless a behavior change is explicitly justified.
### Testing Recommendations
Summarize the verification approach and any cross-cutting test cases, including edge cases and failure scenarios. Keep missing tests as severity-tagged findings and link this section to their IDs.
### Positive Observations
Mention implementation choices that are clear, safe, efficient, or well designed. This is not fluff — it reinforces good patterns and tells the author what to keep doing.
### Final Verdict
Choose one:
- **Approve** — Ready to merge
- **Approve with minor changes** — Good to merge after addressing low/medium issues
- **Request changes** — Critical or high issues must be resolved before merge
List the finding IDs the verdict depends on (e.g. "Request changes: R1, R2").
## Red Flags
- A change merged without any review.
- A review that only checks whether the tests pass.
- Security-sensitive changes without a security-focused review.
- A change too large to review properly: split it.
## Verification
Before emitting the verdict, confirm the evidence the review rests on. This covers the state of the code at review time, not the later fixing of findings:
- [ ] The suite is green, and the evidence is the author's run or CI — not your own re-run. Say which one you relied on.
- [ ] New behavior has tests that cover the edge cases in the diff.
- [ ] The verification story is stated: what changed and how it was verified.
- [ ] Dependency changes were reviewed against the changelog and the lockfile diff.
Return a short summary, findings ordered by impact and a verdict with the
relevant IDs: **Approve**, **Approve with minor changes**, or **Request
changes**. State verification evidence and limitations. Do not duplicate
remedies or tests in separate sections. If no findings exist, say so. In
follow-up, retain original IDs and
report resolved, pending and not-addressed findings as `review-code` requires.

View File

@ -1,322 +1,105 @@
---
name: plan-review-criteria
description: Plan review criteria — the six review axes, severity rubric, approval standard, and output format for reviewing implementation plans. Loaded by the reviewer subagent of the review-plan flow. Not a user-facing flow — to review a plan, use the review-plan flow.
description: Criteria for reviewing implementation plans, including evidence, severity and verdicts. Loaded by the review-plan subagent.
---
# Plan Review Criteria
## Overview
Evaluate whether the plan can deliver its stated goal safely and whether a
skilled implementer can execute and verify it without guessing. Perfect plans
do not exist: do not block on personal preferences or missing sections that
add no useful information. Apply each criterion in proportion to the plan's
scope and risks; explain when a criterion is not applicable.
Multi-dimensional plan review with quality gates. Every plan gets reviewed before implementation starts — no exceptions. Review covers six axes: completeness, task quality, architecture & sequencing, risk coverage, actionability, and proposed code quality.
Follow `review-plan` for delegation, permitted edits, decisions and handover.
Do not run tests, builds or other state-changing checks during the review.
**The approval standard:** Approve a plan when it is specific enough that a skilled implementer could execute it without guessing, the task ordering is sound, and risks are acknowledged. Perfect plans don't exist — the goal is confidence that implementation won't derail. Don't block a plan because it isn't exactly how you would have structured it. If it's executable and well-organized, approve it.
## Evidence and scope
In the `review-plan` flow, apply clear improvements within the plan's existing
goal, scope and decisions. Flag consequential choices for the user instead of
choosing them. Report applied changes and unresolved decisions with evidence,
options and a recommendation; the parent conducts the walkthrough. Recheck the
plan after answers are applied and never approve while required decisions or
changes remain unresolved. Only the plan file may be edited.
- Read the plan, relevant code, project guidance and module memories. Check
that cited paths, symbols and proposed commands exist and are appropriate;
distinguish verified facts from assumptions and unknowns. Do not invent
findings or claim checks were run when they were not.
- Check that tasks serve the stated goal and respect existing requirements and
decisions. Identify scope creep, contradictions and dependencies on external
work. A consequential change in scope, behavior or tradeoffs needs the user's
decision.
- Evaluate the proposed approach even without code snippets: does it solve the
problem, fit existing conventions and avoid unnecessary complexity? If the
plan includes code, also check its types, signatures and examples.
## When to Use
- The reviewer subagent of the `review-plan` flow loads this skill to perform
the review of a plan.
- To review a plan, always go through the `review-plan` flow — never load this
skill directly for that. This is the criteria reference, not the flow.
**Do NOT use for:** Single-file changes with obvious scope, or when the task is trivial enough to just do.
## The Six-Axis Review
Every plan gets evaluated across these dimensions:
## Six review axes
### 1. Completeness
Does the plan cover everything needed to implement successfully?
- Is the **context** clear? (What problem, why now, what's the goal?)
- Are **affected modules** identified with paths?
- Are **architecture decisions** documented with rationale?
- Is there a **testing strategy**?
- Are **verification commands** explicit (not "run the tests")?
- Are **open questions** listed (not buried in someone's head)?
- Is there a **parallelization** assessment for multi-task plans?
**Missing any of these is a gap, not a nit.**
### 2. Task Quality
Are the tasks well-defined and independently executable?
- Does every task have **acceptance criteria**? (Testable, not vague)
- Does every task have **verification steps**?
- Are tasks **sized appropriately**? (XS–M is ideal, L is acceptable, XL must be split)
- Are **dependencies** between tasks explicitly stated?
- Are **files likely touched** listed?
- Is each task a **single, self-contained change**? (Not "implement the whole feature")
- Could a skilled implementer pick up any task and execute it without asking clarifying questions?
### 3. Architecture & Sequencing
Is the plan structured so implementation flows correctly?
- Does implementation order follow the **dependency graph** (foundations first)?
- Are tasks **vertically sliced** (feature paths) rather than horizontally layered?
- Does each task leave the system in a **working state**?
- Are there **checkpoints** between major phases?
- Are **high-risk tasks early** (fail fast)?
- Is the total plan a reasonable number of tasks? (More than ~15 tasks suggests the scope should be split into multiple plans)
### 4. Risk Coverage
Are the hard parts acknowledged and mitigated?
- Are **edge cases** identified?
- Are **breaking changes** or **migration concerns** noted?
- Are **security implications** considered?
- Are **performance implications** considered?
- Are **external dependencies** or integration risks flagged?
- Is there a plan for **rollback** if something goes wrong?
- Are **data integrity** risks addressed (what happens if a migration fails mid-way)?
### 5. Actionability
Can an implementer actually execute this?
- Are **file paths** specific (not "update the relevant files")?
- Are **function/method names** mentioned where applicable?
- Are **verification commands** copy-pasteable (not "run the linter")?
- Are **test commands** project-specific (not generic)?
- Is the **code shape** described where the implementation isn't obvious?
- Are **conventions** referenced (naming, patterns, existing utilities to reuse)?
- Does the plan reference **existing code** the implementer should read first?
### 6. Proposed Code Quality *(when the plan includes implementation details)*
If the plan proposes code shapes, function signatures, data structures, or API designs, evaluate those proposals against `code-review-criteria`:
- **Correctness:** Do the proposed types/signatures handle edge cases (null, empty, boundaries)?
- **Readability:** Are proposed names descriptive and consistent with project conventions?
- **Architecture:** Do proposed abstractions follow existing patterns? Are they justified (not over-engineered)?
- **Security:** Do proposed APIs validate input at boundaries? Any injection/XSS vectors in the design?
- **Performance:** Do proposed data structures avoid N+1 patterns? Any unbounded operations in the design?
**When to apply:** Only when the plan includes specific code snippets, type definitions, API contracts, or function signatures. Plans that only describe "what" without showing "how" skip this axis.
## Structural Remedies
When you flag a structural problem in a plan, propose the fix — not just the problem:
- **A task is too large (XL):** Split it into vertical slices. Each slice should be independently testable.
- **Missing acceptance criteria:** Draft 2–3 specific, testable conditions for the task.
- **Wrong sequencing:** Identify the dependency and propose the correct order.
- **No checkpoints:** Suggest where checkpoints should go (typically after every 2–3 tasks).
- **Vague verification:** Replace "run tests" with the actual project command.
- **Horizontal slicing:** Restructure into vertical feature paths.
- **Missing risk section:** Draft the risks you can identify from the plan content.
Prefer the remedy that makes the plan immediately actionable over one that just flags the gap.
## Plan Sizing
Plans should be scoped to a single deliverable:
```
1–5 tasks → Good. A focused feature or bug fix.
6–10 tasks → Acceptable for a moderate feature.
11–15 tasks → Large. Consider splitting into phases.
15+ tasks → Too large. Split into multiple plans.
```
**What counts as "one plan":** A self-contained set of changes that delivers a single coherent capability. If you can describe the goal in one sentence, it's one plan.
## Categorize Findings
Label every comment with its severity so the author knows what's required vs optional:
| Prefix | Meaning | Author Action |
|--------|---------|---------------|
| *(no prefix)* | Required change | Must address before implementation starts |
| **Critical:** | Blocks implementation | Missing security consideration, data integrity risk, fundamentally wrong approach |
| **Nit:** | Minor, optional | Author may ignore — wording, formatting |
| **Optional:** / **Consider:** | Suggestion | Worth considering but not required |
| **FYI** | Informational only | No action needed — context for future reference |
**Lead with what matters.** Order findings by leverage: missing risks and wrong sequencing first, then task quality gaps, then completeness, then nits. If you have one critical sequencing problem and ten nits, the sequencing problem *is* the review.
## Review Process
### Step 1: Understand the Goal
Before evaluating structure, understand intent:
```
- What is this plan trying to accomplish?
- What problem does it solve?
- What does "done" look like?
```
### Step 2: Check Completeness First
Scan for missing sections before diving into content:
```
- Context present?
- Affected modules listed?
- Architecture decisions documented?
- Risks acknowledged?
- Testing strategy defined?
- Verification commands explicit?
```
### Step 3: Review Task Quality
Walk through each task:
```
For each task:
1. Can I tell exactly what to build?
2. Are acceptance criteria specific and testable?
3. Is the size reasonable (not XL)?
4. Are dependencies clear?
5. Would I know which files to touch?
```
### Step 4: Validate Sequencing
Check the dependency graph:
```
- Are foundations built first?
- Does each task leave the system working?
- Are checkpoints placed correctly?
- Are high-risk items early?
- Is it vertically sliced?
```
### Step 5: Assess Actionability
Put yourself in the implementer's shoes:
```
- Could I pick up task 1 and start coding without asking any questions?
- Are the verification commands copy-pasteable?
- Are file paths and function names specific?
- Is existing code referenced where I'd need to read it?
```
### Step 6: Verify the Verification Story
Check that the plan can actually confirm it worked:
```
- What tests should pass after implementation?
- What build/compile commands are relevant?
- What manual checks are needed?
- How do we know the feature works end-to-end?
```
### Step 7: Evaluate Proposed Code Quality *(if applicable)*
If the plan includes code snippets, types, or API designs:
```
- Load code-review-criteria skill for criteria
- Check proposed signatures for edge cases
- Verify naming follows project conventions
- Confirm abstractions follow existing patterns
- Scan for security vectors in proposed APIs
- Check for performance issues in proposed data structures
```
## Review Checklist
```markdown
## Review: [Plan title]
### Completeness
- [ ] Context explains the problem and goal
- [ ] Affected modules are listed with paths
- [ ] Architecture decisions have rationale
- [ ] Testing strategy is defined
- [ ] Verification commands are explicit and project-specific
- [ ] Open questions are listed
### Task Quality
- [ ] Every task has acceptance criteria
- [ ] Every task has verification steps
- [ ] Tasks are sized XS–M (L acceptable, XL must be split)
- [ ] Task dependencies are stated
- [ ] Files likely touched are listed
### Architecture & Sequencing
- [ ] Order follows dependency graph (foundations first)
- [ ] Vertically sliced (not horizontal layers)
- [ ] Each task leaves system working
- [ ] Checkpoints exist between phases
- [ ] High-risk tasks are early
### Risk Coverage
- [ ] Edge cases identified
- [ ] Breaking changes / migrations noted
- [ ] Security implications considered
- [ ] Performance implications considered
- [ ] Rollback strategy exists (if applicable)
### Actionability
- [ ] File paths are specific
- [ ] Verification commands are copy-pasteable
- [ ] Existing code to read is referenced
- [ ] Conventions and patterns are noted
### Proposed Code Quality *(if plan includes implementation details)*
- [ ] Proposed types/signatures handle edge cases
- [ ] Proposed names follow project conventions
- [ ] Proposed abstractions follow existing patterns
- [ ] No security vectors in proposed APIs
- [ ] No performance issues in proposed structures
### Verdict
- [ ] **Approve** — Ready to implement
- [ ] **Request changes** — Gaps must be addressed
```
## Common Rationalizations
| Rationalization | Reality |
|---|---|
| "I'll figure out the details during implementation" | That's how you discover blocking dependencies mid-task. Surface them now. |
| "The tasks are obvious, no need for criteria" | Write them anyway. Explicit criteria surface hidden assumptions. |
| "It's just a small feature, it doesn't need a plan" | Small features have edge cases too. 3 tasks with criteria takes 5 minutes. |
| "The plan is good enough" | "Good enough" without acceptance criteria means the implementer defines "done" — and they might define it differently. |
| "I'll add verification steps later" | Later never comes. The plan is the contract — define verification now. |
| "Risks are minimal" | Every change has risks. If you can't name them, you haven't thought about them. |
| "The file paths are obvious" | They're obvious to the author. The implementer might not know the codebase. |
| "The code in the plan is fine, it'll get reviewed later" | Plan-level code review catches design problems before implementation — fixing them after coding is more expensive. |
## Red Flags
- No acceptance criteria on any task
- Tasks that say "implement the feature" without specifics
- No verification steps anywhere in the plan
- All tasks are XL-sized
- No checkpoints between phases
- Dependency order isn't considered (e.g., API handler before domain model)
- No testing strategy
- Verification commands are generic ("run tests") instead of project-specific
- Plan has 20+ tasks (scope too large for one plan)
- No risk section on a plan with migrations, breaking changes, or security implications
- Horizontal slicing (all domain, then all services, then all API)
- File paths are vague ("update the relevant files")
- Missing open questions section despite stated unknowns
- Proposed code ignores project conventions or existing patterns
- Proposed types use gratuitous `any`/`unknown`/optional without justification
- Proposed APIs don't validate input at boundaries
## See Also
- For producing plans, use the `planner` skill
- For reviewing implemented code, use `code-review-criteria` — also the criteria source for axis 6
- For security-specific concerns, see `security-and-hardening`
- For testing strategy guidance, see `testing`
Are the problem, intended outcome, affected areas and relevant constraints
clear? Does the plan explain important decisions and include an appropriate
testing strategy? Identify missing information that would change the outcome
or force an implementer to guess. Require risk, rollback, migration or
parallelization details only when relevant.
### 2. Task quality
Are tasks scoped, ordered and specific enough to execute? Check likely files,
dependencies, rationale, acceptance criteria and verification where relevant.
Acceptance criteria should describe observable behavior, including important
failure cases. Split work when it is too large to understand or verify safely,
not merely because it crosses an arbitrary task count.
### 3. Architecture and sequencing
Does the approach fit the existing architecture and reuse appropriate
facilities? Do dependencies precede their consumers, and can the work be
verified as it progresses? Prefer independently testable slices where useful;
use checkpoints where risk or coordination warrants them, not at a fixed
interval. Flag unrelated work or abstractions that add complexity without
helping the goal.
### 4. Risk coverage
Consider relevant edge cases, security, performance, compatibility, data
integrity, migrations and external dependencies. Where failure has meaningful
consequences, check detection, mitigation and rollback or recovery. Do not
invent risks or demand a rollback section for changes that do not need one.
### 5. Actionability and verification
Can the implementer identify the affected code, follow project conventions and
run the stated project-specific checks? Are commands and prerequisites correct?
Do tests and other checks demonstrate the intended behavior and important
failure cases? Surface unknowns honestly rather than presenting an unverified
command or assumption as fact.
### 6. Proposed solution quality
Assess correctness, clarity, architecture, security and performance of the
proposed solution, even when the plan contains no code. For any code sketches,
also check boundary cases, names, types and contracts. Preserve intended
behavior unless a change is explicitly agreed; prefer the simplest solution
that meets the requirements.
## Findings and verdict
Give each reported item a stable ID (`P1`, `P2`, …); retain it throughout the
review and any decision walkthrough. For each item state the evidence, impact,
concrete remedy and verification needed. For a consequential user decision,
include real options, consequences and a recommendation.
- **Blocking:** implementation cannot proceed safely or an essential user
decision remains open. Explain what blocks it.
- **Improvement:** a clear correction that preserves the agreed goal, scope
and behavior. Apply it under `review-plan`'s permitted-edit rules.
- **Optional:** a suggestion that does not prevent implementation. Do not
silently expand scope or override the user's decisions.
Report applied improvements and any outstanding items with their IDs. Give a
provisional verdict before any walkthrough and a final verdict after applying
the decisions:
- **Ready:** no blocking issue or essential decision remains.
- **Awaiting decisions:** user decisions are needed before the plan is ready.
- **Blocked:** required work or evidence is missing and cannot be resolved by
applying clear improvements or obtaining the current decisions alone.
Do not approve an unresolved blocker. A plan may be ready with optional
suggestions; identify them without treating them as required.

View File

@ -29,7 +29,9 @@ Act as a senior software engineer and perform a thorough code review.
code being reviewed.
- Return the COMPLETE review, verbatim, exactly as the skill instructs it to
be produced. Never summarize it.
- Read-only: modify no file and create no commit. Reviewing never writes.
- Read-only: modify no file, create no commit, and run no tests, builds,
linters or other state-changing checks. Use prior results or CI evidence;
state explicitly when evidence is unavailable.
- Do not invent problems: every finding must be real and actionable.
- Missing tests are an issue, not a suggestion — a severity-tagged finding.
- For each finding, give a concrete remedy and the tests needed to verify it.
@ -37,8 +39,8 @@ Act as a senior software engineer and perform a thorough code review.
in that finding. Do not pause to ask during the review.
- Prioritize by impact: one structural issue outweighs ten nits, and "this
could be better" is not a finding — say why and how.
- Skip generated files, lockfile-only changes and unrelated modifications
unless they introduce security risks.
- Inspect generated files and lockfiles when relevant to the change, its
dependencies or security; exclude unrelated working-tree modifications.
3. When the subagent returns, output the review to the user verbatim. Do not
summarize it and do not act on its findings. Retain the subagent session ID,
review target and complete findings in the session context for follow-up;
@ -46,8 +48,8 @@ Act as a senior software engineer and perform a thorough code review.
4. Right after the review, suggest how to proceed based on the findings. These
are suggestions — the user decides:
- **Approve (no required changes):** say so — there is nothing to address.
- **Minor findings (nits):** applying them directly as-is is fine once the
review is done — no plan needed.
- **Minor findings:** suggest direct fixes after the user ends the review if
appropriate; no plan is required.
- **Substantive findings:** suggest `@make-a-plan` to make a plan to address
them.
- If the user wants to discuss findings one by one, use `@issue-walkthrough`
@ -82,9 +84,10 @@ This flow is read-only **for the duration of the review**: from the moment it
starts until the user considers the review finished (including any feedback,
questions, or clarifications about it). During that period, never fix,
implement, edit files or create commits — not even "obvious" fixes derived from
the findings. Once the user explicitly states the review is done (or moves on to
a different task), this rule no longer applies and you act as a normal build
agent again.
the findings. Never run tests, builds, linters or state-changing checks during
the review; inspect existing evidence instead. Once the user explicitly states
the review is done (or moves on to a different task), this rule no longer
applies and you act as a normal build agent again.
## Posting as a GitHub comment
@ -100,7 +103,7 @@ session. PR comments go in English, with this minimal structure:
problem, concrete remedy.
4. **Closing** — optional and short. Cut it when it adds nothing.
Reference every finding by its ID (`R1`, `M1`, `S1`, … from
Reference every finding by its ID (`F1`, `F2`, … from
`code-review-criteria`) so follow-up replies can point to findings
unambiguously.