review-deep

name	review-deep
description	Review change vs spec, plan, code quality heuristics, and repo rules; append remediation phase if needed.
model	sonnet
allowed-tools	["Read","Write","Edit","Glob","Grep","Bash","WebFetch","mcp__*"]

Invoke the unified reviewer in local mode with a stronger reasoning model for deeper analysis. Same comprehensive review framework as /review — validates against specification, implementation plan, code quality heuristics, and repository rules. User invocation: /review-deep [directives...] Examples: /review-deep PDEV-123 /review-deep GH-456 dry run /review-deep PDEV-123 base=staging /review-deep GH-456 head=feat/GH-456/new-endpoint base=production preview only /review-deep PDEV-123 no commit workItemRef='$1' — Tracker reference (e.g., `PDEV-123`, `GH-456`). REQUIRED. directives: remainder free-text. OPTIONAL. Derived flags: baseBranch, headRef, commit (default true), dryRun (default false).

<discovery_rules> Locate change folder: search doc/changes/**/*--<workItemRef>--*/ If not found, search: doc/changes/**/chg-<workItemRef>-spec.md Spec file: chg-<workItemRef>-spec.md; derive slug & change.type from frontmatter. Plan file: chg-<workItemRef>-plan.md Folder pattern: doc/changes/YYYY-MM/YYYY-MM-DD--<workItemRef>--<slug>/ Abort with clear error if spec OR plan missing. </discovery_rules>

<branch_resolution> changeBranch = <change.type>/<workItemRef>/<slug> headRef: directives override, else try changeBranch, fallback: current HEAD. baseBranch: directives override, else main, fallback: master. Compute merge-base and gather symmetric diff baseBranch...headRef. </branch_resolution>

<directive_parsing> Directives (case-insensitive):

• Base branch: base=<branch> | base branch <branch> | compare vs <branch>
• Head ref: head=<ref> | head ref <ref> | branch <ref>
• Disable commit: commit=false | no commit
• Dry run: dry run | preview only Unrecognized tokens ignored. </directive_parsing>

<pre_flight>

1. Validate workItemRef format (uppercase prefix + hyphen + digits).
2. Resolve spec; extract change.type & slug.
3. Resolve plan; parse phases & existing remediation.
4. Load repository rules (AGENTS.md, .ai/rules/**).
5. Resolve branches & compute diff metadata.
6. If dryRun: prepare preview but do NOT write. </pre_flight>

<review_method> The reviewer agent applies its full review framework:

Spec/plan compliance (local mode):

• Scope compliance: changed files align with spec capabilities
• Plan alignment: all tasks done, acceptance criteria have evidence
• Plan task audit: OPEN_TASKS, DONE_BUT_UNCHECKED, CHECKED_BUT_MISSING
• Out-of-scope detection: changes to files not in plan

Code quality heuristics (both modes):

• Full built-in heuristic framework: correctness, security, performance, reliability, API compat, testing gaps, documentation, dependencies
• Repository-local rules from .ai/agent/code-review-instructions.md and .ai/rules/

Ticket context (when available):

• Acceptance criteria verification against implementation
• Linked issue traversal for additional constraints and decisions

The reviewer loads all available context — spec, plan, ticket, repo rules, heuristics — and applies them holistically. Do not duplicate heuristic definitions here; they live in the reviewer agent prompt. </review_method>

<findings_format> [severity: major|minor|nit] <file>[:line] — <description>; fix: <action> </findings_format>

<remediation_phase> If findings exist, append new phase to plan:

### Phase X: Code Review Remediation

- Goal: Address code review findings.
- Tasks:
  - [ ] <precise fix per finding>
- Acceptance criteria:
  - Must: All fixes implemented and validated.
  - Must: Updated tests pass.
- Files and modules: <paths>
- Completion signal: docs(plan): remediate review findings for <workItemRef>

Rules:

• X = max existing phase + 1.
• Do NOT modify earlier phases.
• Append revision log entry. </remediation_phase>

<commit_rules>

• If commit=true and not dryRun: stage plan file, create Conventional Commit via /commit.
• If commit=false: write only.
• Dry run: no write; include preview in output. </commit_rules>

1. Review Summary: pass/fail; changed files count; key themes. 2. Findings: one line per item. 3. Plan Update: "Added Phase X" OR "No plan changes required." OR dry-run preview. 4. Branch info: base, head, changeBranch. 5. Next action: suggest `/run-plan ` if remediation added. - Only modify plan file; never touch spec or code. - Never include `doc/changes/current` in paths. - Idempotent: re-running yields no duplicate tasks. - No external network calls. - Missing spec or plan: abort with message. - Unable to derive slug or change.type: abort. - Branch resolution failure: fallback to HEAD; note in summary. - Empty diff: advisory; no remediation unless plan gaps found.