Standards Review

Quick reference

Review priorities

Phase 0: User confirmation

BEFORE any analysis, ask the user using AskUserQuestion tool:

“Run /simplify at the end for an additional review pass (efficiency, concurrency, hot-paths)? This will increase execution time.”

Remember the answer. If “Yes” - execute Phase 7 after Phase 6. If “No” - stop after Phase 6.

Input

Arguments: $ARGUMENTS

Phase 1: Detect tech stack

Check project root for stack indicators:

ACTION: When stack confirmed — READ references/{stack}.md (relative to this skill directory) and use as expert guidelines.

Multi-stack: If multiple detected, read ALL matching references, process each separately.

Unknown stack: Use only project’s .claude/rules/ — skip stack reference.

Phase 2: Get files

Based on detected stack, use appropriate patterns:

Commands by input type:

# Commit
git diff --name-only {COMMIT}^..{COMMIT} -- {PATTERNS} | head -50

# Branch (auto-detect main/master)
MAIN=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo "main")
git diff --name-only ${MAIN}...HEAD -- {PATTERNS} | head -50

# Folder
find {FOLDER} -type f \( {FIND_PATTERNS} \) | head -50

Phase 3: Load context

Search-first protocol

Before reviewing code: identify new utilities/helpers/patterns/abstractions, then search via grepai_search, check common locations, and decide based on similarity.

Common locations by stack:

Similarity decision matrix:

Phase 4: Expert analysis

Step 4.1: Group files by type

From Phase 2 file list, group by pattern matching:

Java/Kotlin:

TypeScript/React:

Python:

Step 4.2: Spawn experts (haiku per group)

For each non-empty group, spawn parallel haiku agent:

Template:

Task(subagent_type="Explore", model="haiku", prompt="
## Standards Review - {EXPERT_TYPE}

**Stack:** {STACK}
**SEARCH-FIRST:** Use grepai_search for finding existing code before flagging duplicates.

**Files:** {FILE_LIST}

**Project Rules:**
{RULES_CONTENT}

**Stack Guidelines:**
{STACK_REFERENCE_CONTENT}

**Output JSON:**
{
  \"changes\": [{
    \"location\": \"file:15-20\",
    \"description\": \"...\",
    \"existing\": \"path/to/similar|null\",
    \"reuse\": \"REUSE|EXTEND|CONSIDER|KEEP_NEW\",
    \"rating\": \"good|warning|bad\"
  }],
  \"violations\": [{
    \"file\": \"path\",
    \"line\": 42,
    \"rule\": \"avoid#5|best-practice#3|stack:entity-suffix\",
    \"issue\": \"...\",
    \"fix\": \"...\",
    \"severity\": \"error|warning|info\"
  }]
}
")

Phase 5: Validation (sonnet)

Task(subagent_type="reviewer", model="sonnet", prompt="
Validate EACH finding from expert analysis.
Read actual code at file:line locations.
Verify rule actually applies in context.

**Findings:** {AGGREGATED_JSON}

**Output:** [
  {\"id\": \"1\", \"verdict\": \"CONFIRM|REJECT\", \"reason\": \"...\"}
]
")

Phase 6: Report

Create report directory

TIMESTAMP=$(date +"%Y%m%d-%H%M%S")
REPORT_DIR=".claude/reports/${TIMESTAMP}_standards-review"
mkdir -p "${REPORT_DIR}"

REPORT.md structure

# Standards Review Report

**Generated:** {TIMESTAMP}
**Stack:** {DETECTED_STACK}
**Scope:** {INPUT_TYPE} - {INPUT_VALUE}
**Files Reviewed:** {COUNT}

## Summary

| Category | Count | Severity |
|----------|-------|----------|
| Violations | X | Y errors, Z warnings |
| Reuse Opportunities | X | - |
| Good Patterns | X | - |

## Violations

### Errors

| File | Line | Rule | Issue | Fix |
|------|------|------|-------|-----|
| path | 42 | avoid#5 | Description | Suggested fix |

### Warnings

| File | Line | Rule | Issue | Fix |
|------|------|------|-------|-----|

## Reuse Opportunities

| New Code | Existing | Similarity | Action |
|----------|----------|------------|--------|
| path:15-20 | util/X.java | 85% | EXTEND |

## Good Patterns Found

| File | Pattern | Description |
|------|---------|-------------|
| path | stream-api | Proper use of Stream API |

## Reuse Statistics

| Metric | Value |
|--------|-------|
| Total new code blocks | X |
| Reusable (>70%) | Y |
| Reuse rate | Z% |

## Legend

**Severity:** error (must fix), warning (should fix), info (consider)
**Reuse:** REUSE (import), EXTEND (modify existing), CONSIDER (evaluate), KEEP_NEW (justified)
**Rating:** good (exemplary), warning (suboptimal), bad (violation)

Phase 7: Simplify pass (conditional)

Execute ONLY if user answered “Yes” in Phase 0.

After Phase 6 report is written, invoke:

Skill(skill="simplify", args="{INPUT_VALUE}")

Where {INPUT_VALUE} is the same scope used in this review (commit, branch, or folder from Phase 2).

If user answered “No” in Phase 0 - skip this phase entirely.

Error handling