Review Work

Core Principle

Hard Gates

1. Do not receive execution context. No logs from run-plan, no worker output, no diffs, no task completion summaries, no conversation history. The only input is the plan file path.
2. Read the plan document directly. Read the plan file from disk — not a summary or a passed-along description.
3. Run all tests yourself. Do not trust previous execution results. Run the full test suite and every verification command specified in the plan.
4. Verdict is PASS or FAIL. No conditional passes, no "almost done", no "only minor issues remain". Binary only.
5. Save the review document to a file. Review results must be saved as a structured document. Never end with a verbal report alone.
6. Do not modify code. This skill is read-only. If issues are found, report them — do not fix them.

When To Use

• After run-plan execution is complete
• When the user says "review the work", "verify the implementation", "check if the plan was executed correctly"
• When implementation is done but independent verification is needed

When NOT To Use

• While run-plan is still in progress
• When no plan document exists (use

  plan-crafting

  first)
• When the goal is a general code review (this skill verifies "implementation against plan")

Input

docs/engineering-discipline/plans/YYYY-MM-DD-<feature-name>.md

• Execution logs or task completion summaries from run-plan
• Output or diffs from worker subagents
• Validation results from validator subagents
• Conversation history from the execution session

Process

Phase 1: Load and Analyze Plan Document

1. Receive the plan file path as input
2. Read the plan document directly from disk
3. Extract the following:
   • Goal: What this plan implements
   • Work Scope: In scope / Out of scope
   • Task List: Each task's name, acceptance criteria, and target files
   • File Structure Mapping: Complete list of files to be created or modified
   • Commit Structure: Commit messages and scope specified in the plan
   • Test Commands: All test execution commands specified in the plan

Phase 2: Codebase Inspection

1. File existence check: Verify that all files specified in the plan actually exist
2. Content alignment check: Inspect whether each file's content matches the plan's requirements (function signatures, type definitions, logic, etc.)
3. Residual artifact check:
   • Placeholder code (TODO, FIXME, "implement later", stub functions)
   • Debug code (console.log, print debugging, commented-out code blocks)
   • Unexpected changes outside the plan's scope
4. Verify acceptance criteria per task. Check each criterion stated in the plan one by one and record whether it is met.

Phase 3: Test Execution

1. Run all individual test commands specified in the plan
2. Run the full test suite to check for regressions
3. Record each test's result (PASS/FAIL)
4. If any test fails, record the error message

Phase 4: Git History Verification

1. Compare the commit structure specified in the plan against the actual

   git log

2. Verify that commit messages match the plan
3. Verify that each commit's change scope is appropriate (no unrelated changes mixed into a single commit)

Phase 5: Verdict and Review Document

• All files specified in the plan exist
• Each task's acceptance criteria are met
• All tests pass
• No regressions
• No placeholder or debug code remains

• A file specified in the plan is missing
• A test fails
• A regression is found
• Placeholder code remains
• The plan's goal is not achieved

Review Document

Save Location

docs/engineering-discipline/reviews/YYYY-MM-DD-<feature-name>-review.md

Document Structure

# [Feature Name] Review

**Date:** YYYY-MM-DD HH:MM
**Plan Document:** `docs/engineering-discipline/plans/YYYY-MM-DD-<feature-name>.md`
**Verdict:** PASS / FAIL

---

## 1. File Inspection Against Plan

| Planned File | Status | Notes |
|---|---|---|
| `path/to/file` | OK / Missing / Mismatch | Details |

## 2. Test Results

| Test Command | Result | Notes |
|---|---|---|
| `pytest tests/...` | PASS / FAIL | Error details if failed |

**Full Test Suite:** PASS / FAIL (N passed, M failed)

## 3. Code Quality

- [ ] No placeholders
- [ ] No debug code
- [ ] No commented-out code blocks
- [ ] No changes outside plan scope

**Findings:**
- (Describe with file path and line number)

## 4. Git History

| Planned Commit | Actual Commit | Match |
|---|---|---|
| `feat: add X` | `abc1234 feat: add X` | OK / Mismatch |

## 5. Overall Assessment

(Summary of the overall judgment. If FAIL, describe specifically which items failed and why.)

## 6. Follow-up Actions

- (If FAIL: list of items that need to be fixed)
- (If PASS: record improvement suggestions if any)

When To Stop

• The plan file does not exist or cannot be read
• The test execution environment is not ready (e.g., dependencies not installed)
• The plan document format cannot be parsed

Anti-Patterns

Minimal Checklist

• Read the plan document directly from disk
• Did not receive run-plan execution results as input
• Ran all tests myself
• Inspected all tasks in the plan
• Verdict is either PASS or FAIL
• Saved the review document to a file

Transition

• PASS → Report results to the user and suggest next steps (PR creation, deployment, etc.)
• FAIL → Report failure items to the user. If fixes are needed, suggest transitioning to the

  run-plan

  or

  systematic-debugging

  skill
• If the plan itself has issues → suggest returning to the

  plan-crafting

  skill to revise the plan