Code Standards Review

Review current branch changes against software design principles. Surfaces violations of YAGNI, DRY, SRP, Separation of Concerns, and related principles with specific file:line references and actionable suggestions.

When to Use This Skill

• •After completing feature work, before merging
• •As a second-pass review complementing /code-review (which covers bugs, security, performance, testing)
• •When you want a focused check on code design hygiene

When NOT to Use This Skill

• •For bug hunting, security review, or performance analysis (use /code-review)
• •On branches with no commits ahead of main
• •For reviewing the entire codebase (this reviews branch changes only)

The Process (MANDATORY)

Step 1: Gather Context

Determine the default branch and collect the diff:

# Detect default branch
DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo main)

# Current branch
git branch --show-current

# Merge base
MERGE_BASE=$(git merge-base HEAD "origin/$DEFAULT_BRANCH")

# Changed files
git diff --name-only "$MERGE_BASE"..HEAD

# Diff stat
git diff --stat "$MERGE_BASE"..HEAD

Then read every changed file in full using the Read tool. You need full file context to judge whether patterns are violations or intentional design.

Step 2: Analyze Against Each Principle

Review the diff (changed/added lines only) against all 8 principles below. Read surrounding code for context, but only flag issues introduced by this branch.

The first group builds on the coding-patterns skill — use it for detailed patterns, examples, and remediation guidance. The second group is defined fully here.

Principles covered by coding-patterns (review reminders)

For detailed patterns, before/after examples, and fix strategies, invoke the coding-patterns skill.

Principles unique to this review (full definitions)

YAGNI (You Aren't Gonna Need It)

Flag code that builds for hypothetical future requirements rather than current needs:

• •Parameters, config options, or feature flags that no current caller uses
• •Abstract interfaces with only one implementation and no planned second consumer
• •"Extensibility points" (plugin hooks, event systems) with zero current extensions
• •Commented code kept "just in case" or TODO stubs for unplanned features
• •Supporting multiple formats/protocols when only one is used today

Ask: "Is there a current, concrete requirement driving this code?" If not, flag it.

Premature Abstraction

Flag abstractions introduced before enough concrete cases exist to justify them:

• •Generic utility functions used by exactly 1 caller
• •Base classes / interfaces with exactly 1 implementation
• •Shared modules extracted from a single use site
• •Type parameters / generics where a concrete type would work
• •Helper layers that just pass through to another layer without adding logic

The rule of three applies: wait for 3 concrete cases before abstracting. Two is a coincidence; three is a pattern.

Dead/Unused Code

Flag new code introduced by this branch that is unreachable or unreferenced:

• •Exported functions/classes with no importers in the codebase
• •Internal functions that are defined but never called
• •Variables assigned but never read
• •Commented-out code blocks committed alongside active code
• •Catch blocks that silently swallow errors without logging or re-throwing
• •Feature flags or config paths that are never toggled

Unnecessary Complexity

Flag complexity that exceeds what the current problem requires:

• •Feature flags or configuration for behavior that could be hardcoded (single use case)
• •Backwards-compatibility shims for code that was just written in this branch
• •Complex generic types where a simple concrete type suffices
• •Multiple layers of indirection (wrapper → adapter → service → impl) when direct calls work
• •Builder patterns, factories, or registries for constructing simple objects
• •Event-driven architectures for synchronous, single-consumer workflows

Step 3: Report Findings

Use this exact output format. Only include sections for principles where you found violations. Skip clean principles entirely.

## [Principle Name]

**path/to/file.ts:42** — [Description of the violation]
> Suggestion: [Concrete recommendation for what to do instead]

**path/to/file.ts:108** — [Description of the violation]
> Suggestion: [Concrete recommendation for what to do instead]

If the branch is clean across all principles, output:

## No Design Principle Violations Found

The changes in this branch are clean across all 8 design principles reviewed (YAGNI, DRY, SRP, Separation of Concerns, Over-Engineering, Premature Abstraction, Dead/Unused Code, Unnecessary Complexity).

Step 4: Summary

End with a brief summary:

---
**Summary:** X findings across Y principles. [1-2 sentence overall assessment.]

Review Guidelines

• •Scope: Only flag issues in changed/added lines. Read full files for context but don't review pre-existing code.
• •Specificity: Every callout MUST include a file:line reference.
• •Actionability: Every callout MUST include a concrete suggestion. Never flag without offering an alternative.
• •Intent awareness: Don't flag things that are clearly intentional design decisions with good justification visible in the code or commit messages.
• •Signal over noise: Fewer high-quality callouts are better than many marginal ones. If you're unsure whether something is a violation, skip it.
• •No overlap with /code-review: Do NOT comment on bugs, security vulnerabilities, performance issues, test coverage, or documentation. Stay in your lane.