Aif Review

Code Review Assistant

Perform thorough code reviews focusing on correctness, security, performance, and maintainability.

Step 0: Load Config

FIRST: Read .ai-factory/config.yaml if it exists to resolve:

• Paths: paths.description, paths.architecture, paths.rules_file, paths.roadmap, and paths.rules
• Language: language.ui for review summary language
• Git: git.base_branch for branch comparison guidance

If config.yaml doesn't exist, use defaults:

• Paths: .ai-factory/ for all artifacts
• Language: en (English)
• Git: base_branch: main

Behavior

Argument flags

Before routing the argument string into one of the modes below, extract any standalone tokens that flag optional behavior. Strip them from the argument string and route the remainder normally.

• +check — runs the optional findings validator after the review is produced. The full procedure (when to run, failure modes, output additions, gate-result recomputation) lives in references/CHECK-MODE.md. Default is OFF; the validator runs only when this token is present. The token may appear before or after the main argument (e.g. /aif-review +check, /aif-review 123 +check, /aif-review main +check).

If the leftover argument string is empty, fall back to the empty-argument mode (staged review). Unknown +-prefixed tokens are passed through as part of the main argument so they are not silently consumed.

Edge case: a git ref literally named +check will be consumed by the flag stripper — acceptable compromise.

Without Arguments (Review Staged Changes)

1. Run git diff --cached to get staged changes
2. If nothing staged, run git diff for unstaged changes
3. Analyze each file's changes

With PR Number/URL

1. Use gh pr view <number> --json to get PR details
2. Use gh pr diff <number> to get the diff
3. Review all changes in the PR

With Git Ref (Commits Mode)

Argument routing chain:

1. Empty → staged review (see above)
2. Digits or #N → PR mode (see above)
3. Everything else → validate via git rev-parse --verify → commits mode or ask user

Validation:

git rev-parse --verify <argument> 2>/dev/null

• Valid ref → enter commits mode (steps below)

• Invalid ref → do NOT fall back to staged review silently. Ask the user to clarify:

  AskUserQuestion: `<argument>` is not a valid git ref. What did you mean?
  
  Options:
  1. Review staged changes instead
  2. Cancel

  Based on choice:

  • "Review staged changes" → run staged review (default mode)
  • "Cancel" → inform the user that review was cancelled → STOP
  • "Other" → user provides corrected ref → re-validate via rev-parse

Edge case: a branch with a purely numeric name (e.g. 123) will be interpreted as a PR number — acceptable compromise.

Steps:

1. Get commit list between the ref and HEAD:

   git log --oneline --reverse <ref>..HEAD

   If no commits found (HEAD is at or behind <ref>), inform the user and stop.

2. Check commit count: If more than 20 commits, ask the user before proceeding:

   AskUserQuestion: Found <N> commits to review. Reviewing all of them will be slow and consume significant context. How to proceed?
   
   Options:
   1. Review all <N> commits
   2. Review only the last 20
   3. Cancel

   Based on choice:

   • "Review all" → continue with the full commit list
   • "Review only the last 20" → truncate the list to the 20 most recent commits (keep chronological order)
   • "Cancel" → inform the user that review was cancelled → STOP

3. Review each commit:

   git show <commit-hash> --stat
   git show <commit-hash>

   For each commit check:

   • Does the commit message match the actual changes?
   • Are changes atomic (single logical unit per commit)?
   • Are there any issues introduced in this specific commit?

4. Provide combined summary with per-commit notes

Context Gates (Read-Only)

Before finalizing review findings, run read-only context gates:

• Check the resolved architecture artifact (if present) for boundary/dependency alignment issues.
• Check the resolved RULES.md artifact (if present) for explicit convention violations.
• Check the resolved roadmap artifact (if present) for milestone alignment and mention missing linkage for likely feat/fix/perf work.

Human gate result severity:

• WARN for non-blocking inconsistencies or missing optional files.
• ERROR only for explicit blocking criteria requested by the user/review policy.

If the user wants a standalone rules-only pass, suggest /aif-rules-check. Keep human /aif-review gate labels at WARN / ERROR, then append the standard machine-readable gate result with pass|warn|fail status.

Machine-readable gate result

This section is the single owner of aif-gate-result computation:

• Append one final fenced aif-gate-result JSON block after the human-readable review.
• Use "gate": "review".
• "status": "pass|warn|fail" — the more severe (fail > warn > pass) of two independent inputs:
  • findings input — fail when any "Critical Issues" item remains (critical correctness, security, data-loss, performance, downstream regression — see references/SEVERITY.md for the authoritative critical/suggestion definitions); warn when only "Suggestions", missing optional context, or review uncertainty remain; pass when nothing material remains.
  • context-gate input — fail for a blocking (ERROR) gate finding; warn for a non-blocking (WARN) one; pass when none.
  • A failing context gate keeps "status" at fail even with zero Critical Issues — a clean findings list must never mask a failed gate.
• "blocking": true|false — true only when "status" is fail.
• "blockers" — merge-blocking findings only: every "Critical Issues" item and every blocking context-gate finding, nothing else.
• "affected_files" — reviewed or implicated paths.
• "suggested_next.command" follows "status": fail → /aif-fix by default, but if every blocker came from a single context gate point at that gate's command instead (rules gate → /aif-rules, architecture gate → /aif-architecture, roadmap gate → /aif-roadmap); warn/pass → /aif-commit; null only when no command fits.

/aif-review is read-only for context artifacts by default. Do not modify context files unless user explicitly asks.