Brewcode:Standards Review

Standards Review

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 → search via grepai_search, check common locations → decide based on similarity.

Common Locations by Stack:

Similarity Decision Matrix:

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:

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

Standards Review

Analyzes code changes for project standards compliance, detects duplicate code that can be replaced with existing utilities, and highlights exemplary patterns. Automatically detects your tech stack and applies the right set of rules.

Quick Start

/brewcode:standards-review

Reviews all changes on your current branch compared to main.

Modes

Examples

Good Usage

# Review branch before opening a PR
/brewcode:standards-review

# Review a specific commit after a colleague's push
/brewcode:standards-review d8c8e69

# Review an entire module after refactoring
/brewcode:standards-review src/components

# Focus on security concerns in authentication code
/brewcode:standards-review src/auth -p "focus on security and input validation"

# Review Python tests folder for test quality
/brewcode:standards-review tests/

Common Mistakes

# Reviewing generated or vendored code -- produces noise, not actionable findings
/brewcode:standards-review node_modules
/brewcode:standards-review src/generated

# Reviewing the entire repo on a long-lived branch -- too many files, suggest narrowing scope
# (the skill warns you when >50 files are detected)
/brewcode:standards-review /

# Running without any project rules or CLAUDE.md -- the skill still works
# but findings will be limited to stack-specific guidelines only

What It Checks

Standards compliance -- validates code against three layers of rules:

• Project rules from .claude/rules/*.md (numbered avoid#N, best-practice#N)
• Project conventions from CLAUDE.md
• Stack-specific guidelines from built-in reference files

Duplicate detection -- uses grepai_search to find existing utilities, helpers, and patterns before flagging new code. Similarity scoring determines the recommendation:

Pattern recognition -- identifies good patterns worth replicating across the codebase.

Supported stacks:

Multi-stack projects are supported -- each stack is processed separately.

Output

A structured REPORT.md is saved to .claude/reports/{timestamp}_standards-review/ containing:

• Summary table -- violation counts by severity, reuse opportunities, good patterns found
• Violations -- grouped by severity (error, warning, info) with file, line, rule reference, and suggested fix
• Reuse opportunities -- new code mapped to existing code with similarity percentages
• Good patterns -- exemplary code worth emulating
• Reuse statistics -- total new code blocks, reusable percentage, overall reuse rate

Severity levels: error (must fix), warning (should fix), info (consider).

Tips

• Run before opening a PR to catch standards issues early -- the branch diff mode is designed for exactly this workflow.
• If the skill detects more than 50 files, narrow the scope to a specific folder or commit to get more focused results.
• Answer "Yes" to the simplify prompt when reviewing performance-sensitive code -- the extra pass analyzes efficiency, concurrency, and hot-path optimizations.
• Make sure grepai is configured for your project (/brewcode:grepai) to get accurate duplicate detection results.

Documentation

Full docs: standards-review

Java/Kotlin Standards Reference

Standards for Java/Kotlin enterprise projects.

File Patterns

Naming Conventions

Classes

Methods

Dependency Injection

Pattern:

@Service
@RequiredArgsConstructor
public class UserService {
    private final UserRepository userRepository;  // final + constructor
    private final EmailService emailService;
}

Stream API & Functional Style

Violations:

// ❌ Imperative loop
List<String> names = new ArrayList<>();
for (User user : users) {
    names.add(user.getName());
}

// ✅ Stream API
List<String> names = users.stream()
    .map(User::getName)
    .toList();

Immutability

Library Usage Priority

Check existing libraries before writing utility code.

Common JDK Utilities: Null check → Objects.requireNonNull(x, "msg"), Empty → str.isBlank() / collection.isEmpty(), Null-safe equals → Objects.equals(a, b), Optional chain → Optional.ofNullable(x).map(...).orElse(...)

Lombok Annotations

Logging

Test Patterns

Structure

AssertJ

Violations:

// ❌ Too weak
assertThat(result).isNotNull();
assertThat(list).isNotEmpty();

// ✅ Specific
assertThat(result).isEqualTo(expected);
assertThat(list).hasSize(3);

No Conditionals

// ❌ Conditional assertion
if (list.size() > 1) {
    assertThat(list.get(1)).isEqualTo(expected);
}

// ✅ Assert precondition, then assert
assertThat(list).as("precondition").hasSizeGreaterThan(1);
assertThat(list.get(1)).as("second element").isEqualTo(expected);

Kotlin-Specific

Spring Boot Patterns

SQL in Code

Common Violations Summary

Tools

Python Standards Reference

Standards for modern Python projects.

File Patterns

Type Hints

Required Annotations

Pattern:

# ✅ Fully typed
def process_user(user_id: int, options: dict[str, Any] | None = None) -> User:
    ...

# ❌ Missing types
def process_user(user_id, options=None):
    ...

Common Type Patterns

Python 3.10+: Use X | Y over Union[X, Y], list[X] over List[X]

Docstrings

Required Locations

Format (Google Style)

def fetch_user(user_id: int, include_profile: bool = False) -> User | None:
    """Fetch user by ID from database.

    Args:
        user_id: The unique identifier of the user.
        include_profile: Whether to include full profile data.

    Returns:
        User object if found, None otherwise.

    Raises:
        DatabaseError: If database connection fails.
    """

Naming Conventions

Imports

Order (isort)

Style

# ✅ Good
from collections.abc import Callable, Iterable
from pathlib import Path

import httpx
from pydantic import BaseModel, Field

from myapp.models import User
from myapp.utils import validate

# ❌ Bad
from os import *
from myapp.utils import validate, parse, format, convert, transform

Classes

Dataclasses

# ✅ Dataclass
from dataclasses import dataclass

@dataclass(frozen=True)
class User:
    id: int
    name: str
    email: str | None = None

# ✅ Pydantic (with validation)
from pydantic import BaseModel, EmailStr

class UserCreate(BaseModel):
    name: str
    email: EmailStr

No __init__ Boilerplate

Error Handling

Exceptions

# ✅ Specific exception handling
try:
    user = fetch_user(user_id)
except UserNotFoundError:
    logger.warning(f"User {user_id} not found")
    raise
except DatabaseError as e:
    raise ServiceError("Database unavailable") from e

# ❌ Bare except
try:
    ...
except:  # Catches everything including KeyboardInterrupt
    pass

Testing

pytest Patterns

Structure

# test_user_service.py

import pytest
from myapp.services import UserService

class TestUserService:
    """Tests for UserService."""

    def test_get_user_returns_user_when_exists(self, user_service: UserService, sample_user: User):
        # GIVEN
        user_id = sample_user.id

        # WHEN
        result = user_service.get_user(user_id)

        # THEN
        assert result is not None
        assert result.id == user_id
        assert result.name == sample_user.name

    def test_get_user_returns_none_when_not_found(self, user_service: UserService):
        # GIVEN
        nonexistent_id = 99999

        # WHEN
        result = user_service.get_user(nonexistent_id)

        # THEN
        assert result is None

Assertions

Logging

# ✅ Proper logging
import logging

logger = logging.getLogger(__name__)

def process(data: dict) -> None:
    logger.info("Processing data: %s", data.get("id"))
    # ...
    logger.error("Failed to process: %s", error, exc_info=True)

# ❌ Print statements
def process(data):
    print(f"Processing {data}")

Code Style

Line Length & Formatting

Comprehensions

# ✅ Simple comprehension
names = [user.name for user in users if user.active]

# ✅ Generator for large data
active_ids = (user.id for user in users if user.active)

# ✅ Multi-line for complex
results = [
    transform(item)
    for item in items
    if item.valid
    if item.score > threshold
]

Common Violations Summary

Search Locations

Dependency Management

Tools

TypeScript/React Standards Reference

Standards for TypeScript/React projects.

File Patterns

Component Patterns

Functional Components Only

Pattern:

// ✅ Functional component
const UserCard: React.FC<UserCardProps> = ({ user, onEdit }) => {
  return <div>{user.name}</div>;
};

// ❌ Class component
class UserCard extends React.Component { ... }

Component Structure

Hooks

Built-in Hooks

Custom Hooks

Check existing hooks before creating: hooks/ or **/hooks/ directories, use*.ts files, grepai_search for similar functionality

Styling

Theme Tokens

Violations:

// ❌ Hardcoded values
const Button = styled.button`
  color: #3498db;
  padding: 8px 16px;
  font-size: 14px;
`;

// ✅ Theme tokens
const Button = styled.button`
  color: ${({ theme }) => theme.colors.primary};
  padding: ${({ theme }) => theme.spacing.sm} ${({ theme }) => theme.spacing.md};
  font-size: ${({ theme }) => theme.typography.body.size};
`;

Styled Components

TypeScript

Type Safety

Common Patterns

// ✅ Props interface
interface UserCardProps {
  user: User;
  onEdit?: (id: string) => void;
  isLoading?: boolean;
}

// ✅ Discriminated unions
type ApiResponse<T> =
  | { status: 'success'; data: T }
  | { status: 'error'; error: string };

// ❌ Avoid any
const handleData = (data: any) => { ... }

// ✅ Use unknown + narrowing
const handleData = (data: unknown) => {
  if (isUser(data)) { ... }
};

State Management

Local vs Global

Avoid Prop Drilling

Testing

Jest + React Testing Library

Queries Priority:

Test Structure

describe('UserCard', () => {
  it('renders user name', () => {
    // GIVEN
    const user = { id: '1', name: 'John' };

    // WHEN
    render(<UserCard user={user} />);

    // THEN
    expect(screen.getByText('John')).toBeInTheDocument();
  });
});

Performance

Memoization

Avoid premature optimization. Profile first, optimize second.

Code Splitting

Common Violations Summary

Search Locations

Function Declaration Style

Import Order

Tools