kochetkov-ma/brewcode:standards-review

Standards Review

Review Priorities

| Priority | Source | Focus | |----------|--------|-------| | 1 | Existing code | Search FIRST, import instead of creating | | 2 | CLAUDE.md | Project standards, conventions, patterns | | 3 | rules/*.md | Strict rules with numbers — check ALL [avoid#N], [bp#N] | | 4 | references/{stack}.md | Stack-specific guidelines from this skill |

---

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."

| Option | Value | |--------|-------| | A | "Yes - run /simplify after report" | | B | "No - standards review only" |

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

---

Input

| Input | Example | Action | |-------|---------|--------| | Empty | /standards-review | Branch vs main/master | | Commit | abc123 | Single commit | | Folder | src/main/java/... | Folder contents |

Arguments: $ARGUMENTS

Phase 1: Detect Tech Stack

Check project root for stack indicators:

| Files Present | Stack | Reference | |---------------|-------|-----------| | pom.xml, build.gradle, build.gradle.kts | Java/Kotlin | references/java-kotlin.md | | package.json with react/typescript | TypeScript/React | references/typescript-react.md | | pyproject.toml, setup.py, requirements.txt | Python | references/python.md |

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:

| Stack | Patterns | Command | |-------|----------|---------| | Java/Kotlin | *.java, *.kt | git diff --name-only ... -- '*.java' '*.kt' | | TypeScript/React | *.ts, *.tsx, *.js, *.jsx | git diff --name-only ... -- '*.ts' '*.tsx' | | Python | *.py | git diff --name-only ... -- '*.py' |

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

| Source | Files | Condition | |--------|-------|-----------| | Stack reference | references/{stack}.md | Based on Phase 1 detection | | Project rules | .claude/rules/avoid.md, .claude/rules/best-practice.md, .claude/rules/*-avoid.md, .claude/rules/*-best-practice.md, .claude/rules/*.md | May not exist | | Project standards | CLAUDE.md, .claude/CLAUDE.md | May not exist |

Search-First Protocol

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

Common Locations by Stack:

| Stack | Search Paths | |-------|--------------| | Java/Kotlin | **/util/, **/common/, **/shared/, **/core/ | | TypeScript/React | **/components/common/, **/shared/, **/hooks/, **/utils/ | | Python | **/utils/, **/common/, **/lib/, **/helpers/ |

Similarity Decision Matrix:

| Similarity | Decision | Action | |------------|----------|--------| | 90-100% | REUSE | Import existing | | 70-89% | EXTEND | Add params/config to existing | | 50-69% | CONSIDER | Evaluate effort vs benefit | | <50% | KEEP_NEW | Justified new code |

Dynamic Agent Resolution

Before spawning expert agents, check for project team agents:

1. If .claude/teams/ exists — read team.md for agent roster with domains
2. If team has code-quality/standards domain agents — prefer over generic reviewer/Explore
3. Priority: team agent > project agent > plugin agent > system agent
4. If agent refuses (Task Acceptance Protocol) — re-delegate to suggested colleague (max 2 retries)

Always fall back to plugin agents when no project agents match the task domain.

Phase 4: Expert Analysis

Step 4.1: Group Files by Type

From Phase 2 file list, group by pattern matching:

Java/Kotlin:

| Group | Pattern | Focus | |-------|---------|-------| | entities | **/entity/*.java, **/model/*.kt | Entity suffix, DI, Lombok | | services | **/service/*.java, **/service/*.kt | Stream API, constructor injection | | tests | **/*Test.java, **/*Test.kt | AssertJ, BDD comments, no logs | | build | pom.xml, build.gradle, build.gradle.kts | Dependencies, plugins, versions |

TypeScript/React:

| Group | Pattern | Focus | |-------|---------|-------| | styles | **/styles.ts, **/*.styled.ts | Theme tokens, no hardcoded colors | | components | **/*.tsx | Hooks, functional components | | tests | **/*.test.tsx, **/*.spec.ts | Jest patterns, coverage | | build | package.json, tsconfig*.json, vite.config.*, webpack.config.* | Dependencies, scripts, bundler config |

Python:

| Group | Pattern | Focus | |-------|---------|-------| | modules | **/*.py (non-test) | Type hints, docstrings | | tests | **/test_*.py, **/*_test.py | pytest patterns | | configs | **/config*.py, **/settings*.py | Environment handling | | build | pyproject.toml, setup.py, setup.cfg, requirements*.txt | Dependencies, tool configs |

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

| Condition | Action | |-----------|--------| | No files found | Exit: "No files to review for {SCOPE}" | | >50 files | Warn user, suggest narrowing scope | | Unknown stack | Continue with project rules only | | No rules found | Continue with stack reference only | | All compliant | Report: "All code compliant with standards" |