Review

Code Forge — Review

Comprehensive code review against reference documents and engineering best practices. Covers functional correctness, security, resource management, code quality, architecture, performance, testing, error handling, observability, maintainability, backward compatibility, and dependency safety.

Supports four modes:

• Feature mode: Review a single feature against its plan.md
• Project mode: Review the entire project against planning documents or upstream docs
• Feedback mode: Evaluate and respond to incoming code review comments (--feedback)
• GitHub PR mode: Post a 14-dimension review as a comment on a GitHub PR (--github-pr)

When to Use

• Feature implementation is complete or nearly complete
• Want to verify code quality before creating a PR
• Need a structured review against the original plan or documentation
• Want a holistic project-level quality check
• Received code review feedback and need to evaluate/respond to it (--feedback)
• Want to post a code review directly to a GitHub PR for team visibility (--github-pr)

Examples

/code-forge:review user-auth             # Review a specific feature
/code-forge:review --project             # Full project review
/code-forge:review                       # Auto-detect features to review
/code-forge:review --feedback            # Evaluate incoming review comments
/code-forge:review --github-pr 123       # Post review to GitHub PR #123
/code-forge:review user-auth --save      # Review and save report to disk

Workflow

Config → Determine Mode → Locate Reference → Collect Scope → Multi-Dimension Review (sub-agent) → Display Report → Update State → Summary

Context Management

The review analysis is offloaded to a sub-agent to handle large diffs without exhausting the main context.

Review Severity Levels

All issues use a 4-tier severity system, ordered by merge-blocking priority:

Review Dimensions Reference

For the full list of 14 review dimensions with check items, read references/dimensions.md.

Quick summary by tier:

• Tier 1 (Must-Fix): D1 Functional Correctness, D2 Security, D3 Resource Management
• Tier 2 (Should-Fix): D4 Code Quality, D5 Architecture, D6 Performance, D7 Test Coverage
• Tier 3 (Recommended): D8 Error Handling, D9 Observability, D10 Standards
• Tier 4 (Nice-to-Have): D11 Backward Compat, D12 Maintainability, D13 Dependencies, D14 Accessibility (frontend only)

Dimension Application Rules:

• D1–D3: Always apply. Potential merge blockers.
• D4–D7: Always apply. Should-fix items.
• D8–D10: Always apply. Flag as warnings/suggestions.
• D11–D13: Always apply but expect mostly suggestions.
• D14: Apply ONLY if project_type is "frontend" or "fullstack".

When spawning review sub-agents, instruct them to read references/dimensions.md for the full check items.

Detailed Steps

@../shared/configuration.md

Step 1: Determine Review Mode

Parse the user's arguments to determine which mode to use.

1.0a --github-pr Flag Provided

If the user passed --github-pr (e.g., /code-forge:review --github-pr or /code-forge:review --github-pr 123):

→ GitHub PR Mode — Read and follow skills/review/github-pr-workflow.md. Do NOT continue with the steps below.

1.0b --feedback Flag Provided

If the user passed --feedback (e.g., /code-forge:review --feedback or /code-forge:review --feedback #123):

→ Feedback Mode — Read and follow skills/review/feedback-workflow.md. Do NOT continue with the steps below.

1.1 Feature Name Provided

If the user provided a feature name (e.g., /code-forge:review user-auth):

→ Feature Mode — go to Step 2F

1.2 --project Flag Provided

If the user passed --project (e.g., /code-forge:review --project):

→ Project Mode with scope = "full" — go to Step 2P

1.3 No Arguments

If no arguments provided:

1. Scan both {output_dir}/*/state.json and .code-forge/tmp/*/state.json for all features
2. Filter to features with at least one "completed" task
3. Build choice list:
   • If completed features exist: include each as an option, plus "Review entire project" as the last option
   • If no completed features: go to Project Mode with scope = "changes" automatically
4. If only one option (project review): go to Project Mode with scope = "changes" automatically
5. If multiple options: use AskUserQuestion to let user select
   • If user selects "Review entire project": go to Project Mode with scope = "changes"

Step 2F: Feature Mode — Locate Feature

2F.1 Find Feature

1. Look for {output_dir}/{feature_name}/state.json
2. If not found, also check .code-forge/tmp/{feature_name}/state.json
3. If still not found: show error, list available features

2F.2 Load Feature Context

1. Read state.json
2. Read plan.md (for acceptance criteria and architecture)
3. Note completed task count and overall progress

→ Go to Step 3F

Step 2P: Project Mode — Locate Reference

Determine the reference level using a fallback chain.

2P.1 Check for Planning Documents (Level 1: Planning-backed)

Scan {output_dir}/*/plan.md:

• If one or more plan.md files found → planning-backed
• Read all plan.md files and aggregate:
  • Acceptance criteria from each feature
  • Architecture decisions
  • Technology stack
• Read corresponding state.json files for progress context
• Record: reference_level = "planning"
• Record: list of plan file paths and aggregated criteria
• → Go to Step 3P

2P.2 Check for Documentation (Level 2: Docs-backed)

If no planning documents found, scan for upstream documentation:

Search paths (in order):

1. {input_dir}/*.md — feature specs
2. docs/ directory — PRD, SRS, tech-design, test-plan files

Look for files matching patterns:

• **/prd.md, **/srs.md, **/tech-design.md, **/test-plan.md
• **/features/*.md
• Any .md files directly under docs/

If documentation files found → docs-backed:

• Read all found docs
• Extract: requirements, architecture decisions, acceptance criteria, scope definitions
• Record: reference_level = "docs"
• Record: list of doc file paths and extracted criteria
• → Go to Step 3P

2P.3 No Reference (Level 3: Bare)

If neither planning nor docs found → bare:

• Record: reference_level = "bare"
• → Go to Step 3P

Step 3F: Feature Mode — Collect Changes and Review

3F.1 Collect Change Scope

From Commits: Extract all commit hashes from state.json → tasks[].commits:

• Flatten all commit arrays into a single list
• If commits are recorded, use git diff between the earliest and latest commits
• If no commits recorded, fall back to scanning files involved in tasks

From Task Files: Read all tasks/*.md files and collect their "Files Involved" sections:

• Build a complete list of files created/modified by this feature
• Read current state of each file

Summary:

• Total files changed
• Total lines added/removed (from git diff)
• List of all affected files

3F.2 Detect Project Type

Before launching the sub-agent, detect the project type to guide dimension selection:

1. Has frontend? Check for: *.tsx, *.jsx, *.vue, *.svelte, HTML templates, CSS/SCSS files, or frontend framework config (next.config.*, vite.config.*, angular.json)
2. Has backend/service? Check for: server entry points, API route definitions, database models, middleware
3. Language ecosystem: Detect primary language(s) from file extensions and package manifests

Record: project_type = "frontend" | "backend" | "fullstack" | "library" | "cli" | "unknown"

3F.3 Multi-Dimension Review (via Sub-agent)

Offload to sub-agent to handle the full diff analysis.

Spawn an Agent tool call with:

• subagent_type: "general-purpose"
• description: "Review feature: {feature_name}"

Sub-agent prompt must include:

• Feature name and plan.md file path
• List of all affected files (sub-agent reads them)
• The acceptance criteria from plan.md
• Detected project type
• Instructions to review across all applicable dimensions below
• The severity level definitions (blocker / critical / warning / suggestion)
• Instruction: "For each issue, specify severity, file path, line number/range, what's wrong, and how to fix it. Use the Review Comment Formula: Problem → Why it matters → Suggested fix."

Review dimensions to apply: Follow Dimension Application Rules.

Additionally, always check Plan Consistency (feature mode specific):

• All acceptance criteria from plan.md are met
• Architecture matches the design in plan.md
• No unplanned features added (scope creep)
• All planned tasks are implemented

Sub-agent must return the structured format defined in references/sub-agent-format.md (use the Feature Mode PLAN_CONSISTENCY consistency section).

→ Go to Step 4F

Step 3P: Project Mode — Collect Source Code and Review

The primary subject of review is the source code itself. Reference documents (plans, specs) serve only as criteria to check against — the sub-agent must deeply read and analyze the actual implementation.

3P.1 Collect Source Code

Identify and collect project source files for deep code review. The collection strategy depends on scope (set in Step 1):

If scope = "changes" (default — no arguments or auto-selected):

1. Identify changed files (primary scope):

   • If on a non-main branch: git diff main...HEAD --name-only
   • If on main branch with uncommitted changes: git diff HEAD --name-only + git diff --cached --name-only (staged + unstaged)
   • If on main branch with no uncommitted changes: git diff HEAD~1 --name-only (last commit)
   • Exclude non-source directories: node_modules/, dist/, build/, .git/, vendor/, __pycache__/, the output directory itself

2. Expand to impact zone (1 level): For each changed file, also include:

   • Files that import or depend on the changed file (direct dependents — use Grep to find import/require/use statements referencing the changed file)
   • Files that the changed file imports from (direct dependencies — read the changed file's import statements)
   • Test files corresponding to the changed files (e.g., foo.test.ts for foo.ts)

3. Fallback to full scan: Only if no changed files are found (clean repo, no recent commits), fall through to the scope = "full" strategy below.

If scope = "full" (--project flag):

1. Use project root markers to find source directories (e.g., src/, lib/, app/, pkg/, or language-specific patterns)
2. Exclude non-source directories: node_modules/, dist/, build/, .git/, vendor/, __pycache__/, the output directory itself
3. Scan all source files
4. If the project is large (>50 source files), prioritize:
   • Core modules (entry points, main logic, business logic)
   • Test files
   • Configuration and infrastructure files

Both modes also collect:

• Package manifests (package.json, Cargo.toml, pyproject.toml, etc.) for dependency review
• Build/CI configuration if present

3P.2 Detect Project Type

Same as Step 3F.2 — detect project_type to guide dimension selection.

3P.3 Multi-Dimension Code Review (via Sub-agent)

Offload to sub-agent to handle deep source code analysis.

Spawn an Agent tool call with:

• subagent_type: "general-purpose"
• description: "Project code review: {project_name}"

Sub-agent prompt must include:

• Project name and root path
• List of all source files to review — sub-agent MUST read and analyze each file's actual implementation
• Reference level (planning / docs / bare) and associated criteria (if any)
• Detected project type
• If planning-backed: aggregated acceptance criteria (as checklist for consistency dimension only)
• If docs-backed: extracted requirements (as checklist for consistency dimension only)
• The severity level definitions (blocker / critical / warning / suggestion)
• Explicit instruction: "Read every source file. Review the code itself — its logic, structure, correctness, and quality. Reference documents are only used as criteria for the consistency check, not as the subject of review."
• Instruction: "For each issue, specify severity, file path, line number/range, what's wrong, and how to fix it. Use the Review Comment Formula: Problem → Why it matters → Suggested fix."

Review dimensions to apply: Follow Dimension Application Rules.

Additionally, apply the appropriate Consistency check based on reference level:

• planning-backed → Plan Consistency:

  • Aggregated acceptance criteria from all plans are met in the code
  • Implemented architecture matches the designs in plan files
  • No unplanned features added (scope creep)
  • All planned features have corresponding code

• docs-backed → Documentation Consistency:

  • Code implements the requirements described in documentation
  • Architecture aligns with tech design (if present)
  • Feature scope in code matches what specs describe
  • No undocumented major functionality in the code

• bare → Skip this dimension. Note in the report: "No reference documents found — consistency check skipped."

Sub-agent must return the structured format defined in references/sub-agent-format.md (use the Project Mode CONSISTENCY consistency section). All issues MUST reference specific source files and line numbers/ranges.

→ Go to Step 4P

Step 4F: Feature Mode — Display Report

Review results are displayed in the terminal by default — no file is written. This reflects that reviews are iterative, intermediate checks rather than permanent artifacts.

Follow the report template in references/report-template.md (Feature mode variant).

4F.1 Optional: Save to File (--save)

If the user passed --save in the arguments, also write the report to {output_dir}/{feature_name}/review.md. Otherwise, do NOT create the file.

→ Go to Step 5F

Step 4P: Project Mode — Display Report

Follow the report template in references/report-template.md (Project mode variant).

4P.1 Optional: Save to File (--save)

If the user passed --save in the arguments, also write the report to {output_dir}/project-review.md. Otherwise, do NOT create the file.

→ Go to Step 5P

Step 5F: Feature Mode — Update state.json

1. Read state.json
2. Add or update review field in metadata:

   {
     "review": {
       "date": "ISO timestamp",
       "rating": "pass_with_notes",
       "merge_readiness": "fix_required",
       "total_issues": 12,
       "blockers": 0,
       "criticals": 2,
       "warnings": 6,
       "suggestions": 4
     }
   }
   

   • If --save was used, also include "report": "review.md" in the review object
3. Update state.json updated timestamp

→ Go to Step 6

Step 5P: Project Mode — No State Update

Project mode does not update any state.json — there is no single feature state to track.

→ Go to Step 6

Step 6: Summary and Next Steps

6.1 Feature Mode

Display:

Code Review Complete: {feature_name}

Rating: {overall_rating}
Merge Readiness: {merge_readiness}
Issues: {total_issues} ({blocker_count} blockers, {critical_count} critical, {warning_count} warnings, {suggestion_count} suggestions)
{If --save was used:}
Report saved: {output_dir}/{feature_name}/review.md

{If needs_changes (blockers or criticals > 0):}
🚫 Merge blocked — fix these first:
  1. {highest priority blocker/critical with file:line}
  2. {next priority fix}
  ...
  Fix all:    /code-forge:fixbug --review
  Re-review:  /code-forge:review {feature_name}

{If pass_with_notes (warnings > 0, no blockers/criticals):}
⚠ Merge OK with notes — consider fixing:
  1. {top warning}
  2. ...
  Fix all:    /code-forge:fixbug --review

{If pass:}
✅ Ready for next steps:
  /code-forge:status {feature_name}         View final status
  Create a Pull Request

Tip: use --save to persist the review report to disk

6.2 Project Mode

Display:

Project Review Complete: {project_name}

Rating: {overall_rating}
Merge Readiness: {merge_readiness}
Reference: {planning-backed (N plans) | docs-backed (N documents) | bare}
Issues: {total_issues} ({blocker_count} blockers, {critical_count} critical, {warning_count} warnings, {suggestion_count} suggestions)
{If --save was used:}
Report saved: {output_dir}/project-review.md

{If needs_changes (blockers or criticals > 0):}
🚫 Issues require attention:
  1. {highest priority blocker/critical with file:line}
  2. {next priority fix}
  ...
  Fix all:    /code-forge:fixbug --review
  Re-review:  /code-forge:review --project

{If pass_with_notes (warnings > 0, no blockers/criticals):}
⚠ Project quality acceptable with notes — consider fixing:
  1. {top warning}
  2. ...
  Fix all:    /code-forge:fixbug --review

{If pass:}
✅ Project quality looks good.

Tip: use --save to persist the review report to disk