Inspect Work

Inspect Work

Review completed task implementation across three dimensions: does it match the spec, is the code well-written, and is it secure? This is a structured review, not a rubber stamp.

Process Flow

digraph inspect_work {
    "Read task spec + diff" [shape=box];
    "Stage 1: Spec compliance" [shape=box];
    "Spec passes?" [shape=diamond];
    "Stage 2: Code quality" [shape=box];
    "Quality passes?" [shape=diamond];
    "Stage 3: Security scan" [shape=box];
    "Security passes?" [shape=diamond];
    "Report: all clear" [shape=doublecircle];
    "Report: issues found" [shape=box];
    "Implementer fixes" [shape=box];
    "Re-review fixed items" [shape=box];
    "3 loops exceeded?" [shape=diamond];
    "Escalate to drive-execution" [shape=box];

    "Read task spec + diff" -> "Stage 1: Spec compliance";
    "Stage 1: Spec compliance" -> "Spec passes?";
    "Spec passes?" -> "Stage 2: Code quality" [label="yes"];
    "Spec passes?" -> "Report: issues found" [label="no"];
    "Stage 2: Code quality" -> "Quality passes?";
    "Quality passes?" -> "Stage 3: Security scan" [label="yes"];
    "Quality passes?" -> "Report: issues found" [label="no"];
    "Stage 3: Security scan" -> "Security passes?";
    "Security passes?" -> "Report: all clear" [label="yes"];
    "Security passes?" -> "Report: issues found" [label="no"];
    "Report: issues found" -> "Implementer fixes";
    "Implementer fixes" -> "Re-review fixed items";
    "Re-review fixed items" -> "3 loops exceeded?";
    "3 loops exceeded?" -> "Escalate to drive-execution" [label="yes"];
    "3 loops exceeded?" -> "Spec passes?" [label="no, spec stage"];
    "3 loops exceeded?" -> "Quality passes?" [label="no, quality stage"];
    "3 loops exceeded?" -> "Security passes?" [label="no, security stage"];
}

Three-Stage Review

Stage 1: Spec Compliance

• Does the implementation match what was planned?
• Are all requirements from the task description addressed?
• Are there additions not in the spec (scope creep)?
• Do types, method names, and interfaces match what was designed?

Stage 2: Code Quality

• Is the code readable and well-structured?
• Are functions focused (single responsibility)?
• Is error handling present and appropriate?
• Are there code smells (duplication, deep nesting, magic values)?
• Do tests actually test meaningful behavior (not just coverage)?

Stage 3: Security

• Is user input validated and sanitized?
• Are SQL queries parameterized?
• Are secrets kept out of code?
• Are authentication/authorization checks present where needed?
• Are error messages safe (no internal details leaked)?

Re-Review Loop

When a review stage finds issues, the implementer fixes them and the reviewer re-reviews. This is not optional.

1. Reviewer reports issues with severity (Critical / Important / Suggestion)
2. Critical: implementer MUST fix. Important: implementer SHOULD fix (can defer with written rationale). Suggestions: noted, no action required.
3. After fixes: reviewer re-reviews ONLY the fixed items (not a full re-review)
4. Loop repeats until no critical issues remain and all important items are fixed or acknowledged
5. Maximum 3 loops per stage. After 3, escalate to drive-execution for human input.

For reviewer prompt templates, see reviewer-prompts.md. For the full protocol, see re-review-protocol.md.

Issue Severity

Categorize every finding:

Anti-Patterns

"Looks good to me" A review with no findings is suspicious. Every piece of code has something worth noting, even if it is a suggestion. If you found nothing, you did not look hard enough.

"I'll just review the final result at the end" Review per task, not per project. Issues compound. A wrong abstraction in task 2 infects tasks 3 through 8.

"The tests pass so the code is correct" Tests verify behavior, not quality. Passing tests with SQL injection vulnerabilities still pass tests.

Evidence Requirements

• Review report exists with findings categorized by severity
• All critical issues are resolved before the task is marked complete
• The review explicitly covers all three stages

Transition

If all stages pass (no critical issues): return to drive-execution to proceed with the next task. If critical issues found: return to prove-first for the implementer to fix.