Automated Code Review

Relevant source files

The following files were used as context for generating this wiki page:

• skills/code-review/SKILL.md
• skills/repo-production-workflow/SKILL.md
• skills/code-quality/SKILL.md
• CLAUDE.md
• skills/production-code/SKILL.md
• skills/production-preflight/SKILL.md

Automated code review provides a systematic process for evaluating code diffs against independent Standards and Spec axes. The system functions as a fresh-context reviewer that operates within a governed production workflow to identify defects, quality violations, and behavioral regressions. It ensures that changes remain minimal, direct, and verified before integration into the repository.

Sources: skills/code-review/SKILL.md:1-6, skills/repo-production-workflow/SKILL.md:167-172

Workflow Integration

The code review process occurs after implementation and verification but before final workflow completion. It utilizes a delegated agent (typically claude-fable-5-1) to perform the analysis in a temporary state to avoid mutating the active checkout.

The diagram shows the sequential steps from implementation to final review within the production workflow.
Sources: skills/repo-production-workflow/SKILL.md:167-194, skills/code-review/SKILL.md:10-14

Review Axes and Rubrics

The system evaluates code across two primary axes: Standards and Spec. Each finding must state severity, materiality, a reproducing command, and the expected versus observed effect.

Standards Axis

This axis focuses on technical debt, violations of documented standards, and architectural smells. It utilizes the code-quality rubric to enforce seven core principles.

Principle	Focus
Minimal Code	Smallest correct change; removal of obsolete code.
No Duplicated Behavior	Reuse of existing owners; once-only implementation.
Direct Flow	Explicit I/O and state transitions; validation at boundaries.
No Fake-Green	Canonical mock ban; no swallowing of real failures.
Cleanup Discipline	Removal of temporary artifacts and dead code.
Consequence Coverage	Tracing impact on callers, callees, and adjacent surfaces.
Simple Implementation	Readable, direct code without excessive ceremony.

Sources: skills/code-review/SKILL.md:65-71, skills/code-quality/SKILL.md:13-52

Spec Axis

The Spec axis evaluates the implementation against requirements and behavioral contracts. It identifies missing requirements, unauthorized behavior, and contradictions between implementation limits and interface claims.

Sources: skills/code-review/SKILL.md:72-76

Review Process Steps

The automated reviewer follows a structured six-step process to ensure thoroughness and accuracy:

1. Fix the Target: Read the contract and identity (intent, workflowId, baseOid) from the workflow status tool. Record repository metadata and dirty/staged states.
2. Read the Affected Surface: Inspect changed files, direct callers, callees, and governing artifacts using GitNexus evidence.
3. Apply Rubrics: Use code-quality for principles and codebase-design for architectural judgment.
4. Falsify Promises: Challenge the implementation by separating intentional changes from regressions. Run the smallest real-interface attacks to distinguish expected vs. observed behavior.
5. Review Axes: Run Standards and Spec evaluations independently.
6. Return Structured Output: Provide a human-readable report followed by an immutable JSON finding intake.

Sources: skills/code-review/SKILL.md:16-88

Finding Disposition and Management

Every material finding must be resolved before a workflow can be completed. The lead developer is responsible for the disposition of findings through the workflow.py interface.

The sequence diagram illustrates the communication between the review delegate and the lead agent when managing review findings.
Sources: skills/repo-production-workflow/SKILL.md:183-205

Hard Invariants and Bans

The automated review enforces non-negotiable hard invariants defined in the project's global rules.

• Mock Ban: Verification must cross the real production interface. Mocks, stubs, or test-only adapters are forbidden for RED/GREEN proof.
• Imaginary-Risk Ban: Theoretical failures do not justify code changes. A verified mechanism or demonstrated occurrence is required before changing behavior.
• Root-Cause-First Gate: Fixes must target the source trigger, not the visible symptom. Implementation requires a reproduced symptom and a testable hypothesis.

Sources: CLAUDE.md:21-41

Structured Output Format

Review findings are returned in a specific JSON format to ensure machine-readability and integration with the workflow ledger.

{
  "findings": [
    {
      "id": "SPEC-1",
      "axis": "Spec",
      "severity": "high",
      "material": true,
      "kind": "behavioral",
      "location": "path/to/file.py:42",
      "claim": "The module should handle null inputs.",
      "evidence": "Inputting None causes an unhandled AttributeError.",
      "consequence": "System crashes on unvalidated external payloads.",
      "smallest_action": "Add boundary validation for null check."
    }
  ]
}

Sources: skills/code-review/SKILL.md:80-88

The automated code review system ensures that all repository changes adhere to strict quality standards and behavioral contracts. By enforcing systematic rubrics, banning mocks in verification, and requiring material dispositions for every finding, the system maintains a high-integrity production codebase.

Sources: skills/code-review/SKILL.md:1-88, skills/repo-production-workflow/SKILL.md:167-205