my-vault/.claude/commands/pragmatic-review.md

name, description, version, argument-hint, allowed-tools

name	description	version	argument-hint	allowed-tools
pragmatic-review	Interactive pragmatic code review focusing on YAGNI and KISS principles	1.0.0	[--auto] [--ci] [--deep (6-pass)] [--branch branch-name] [--base base-branch]	Read Grep Glob Bash(test:*) Bash(git:*) Bash(echo:*) Bash(head:*) Bash(wc:*) Bash(tr:*)

Pragmatic Code Review: YAGNI & KISS Focus

You will perform an interactive code review with laser focus on YAGNI (You Aren't Gonna Need It) and KISS (Keep It Simple, Stupid) principles.

Review Modes

Default mode: Fast YAGNI/KISS-focused review

• Scans for over-engineering, unused abstractions, unnecessary complexity
• Quick security and performance checks (OWASP basics, obvious N+1 queries)
• Self-reflection to validate findings with evidence

Deep mode (--deep flag): Multi-pass comprehensive review

• Pass 1: Security (OWASP Top 10, input validation, auth issues)
• Pass 2: Architecture (SOLID principles, separation of concerns)
• Pass 3: Logic (edge cases, error handling, correctness)
• Pass 4: Performance (algorithm complexity, resource leaks)
• Pass 5: YAGNI/KISS (over-engineering, unnecessary abstractions)
• Pass 6: Maintainability (readability, tests, documentation)
• Self-reflection after all passes

Use --deep when:

• Security-critical changes (auth, payment, data handling)
• Core architecture modifications
• Complex logic changes with many edge cases
• Performance-sensitive code paths

Use default mode when:

• Feature additions
• Bug fixes
• Refactoring
• Documentation changes

CI mode (--ci flag): Non-interactive mode for GitHub Actions

• Skips ALL interactive prompts
• Auto-selects: all branch changes vs base branch
• Uses $GITHUB_BASE_REF environment variable if available
• Outputs all findings at once as markdown (summary view)

Step 1: Determine Review Scope

Check Current Git State

First, verify we're in a git repository by running:

• test -d .git to check if .git directory exists

If not in a git repository, ask the user to specify files to review manually.

If in a git repository, gather information:

Current branch:

Run: git rev-parse --abbrev-ref HEAD

Default branch detection:

1. Try: git rev-parse --verify main
2. If that fails, try: git rev-parse --verify master
3. If that fails, try: git rev-parse --verify develop

If user specified --base [branch] in arguments, use that instead.

Working directory status:

Run: git status --short | head -20

Present Options to User

If --ci flag is present: Skip all interactive prompts and auto-select option 2: Review all changes on current branch vs base.

Unless --auto or --ci flag is present, ask the user:

📋 CODE REVIEW SCOPE SELECTION
════════════════════════════════

What would you like to review?

1️⃣  Current uncommitted changes
2️⃣  All changes on current branch (compared to [detected default branch])
3️⃣  Specific files or directory
4️⃣  Last N commits
5️⃣  Staged changes only

Please enter your choice (1-5):

Step 2: YAGNI/KISS Analysis Framework

For each file identified, analyze for these patterns:

YAGNI Detection Patterns

1. Unused abstractions

   • Interfaces/protocols with single implementations
   • Abstract base classes with one concrete subclass
   • Generic types that are always the same

2. Premature flexibility

   • Configuration for things that never change
   • Plugin systems with no plugins
   • Feature flags that are always on/off

3. Over-engineering indicators

   • Factory classes for simple objects
   • Builder patterns for objects with 2-3 fields
   • Event systems with single listeners

4. Speculative code

   • "TODO: might need this" comments
   • Commented-out code "just in case"
   • Unreachable code paths
   • Methods that are never called

5. The GenericButton Anti-Pattern

   • Components with 8+ optional parameters serving different use cases
   • So many props that using it is as complex as writing from scratch

6. Premature Abstraction - Rule of Three

   • Abstraction created at 1st or 2nd duplication (wait for 3rd!)
   • Reference: Martin Fowler - "Tolerate duplication twice, refactor on the third"

KISS Violation Patterns

1. Verbose implementations

   • Can be reduced by >50% lines
   • Reimplements standard library functions
   • Complex regex when simple string operations work

2. Abstraction addiction

   • More than 3 levels of inheritance/wrapping
   • Interfaces between every layer

3. Clever code

   • Needs extensive comments to explain
   • Uses obscure language features unnecessarily
   • One-liners that should be 5 clear lines

4. Catch-Log-Exit Anti-Pattern

   • Catching exceptions just to log and exit
   • Replaces actual error with a guess about what went wrong

   // TERRIBLE: replaces actual error with a guess
   try {
     await createNewBranch({ branchName, cwd })
   } catch (error) {
     console.error('Error: Not in a git repository') // Maybe wrong!
     process.exit(1)
   }
   
   // CORRECT: let it throw naturally
   await createNewBranch({ branchName, cwd })
   

Security Patterns to Check

Even in a YAGNI/KISS review, flag critical security issues:

1. SQL Injection

   • String concatenation in SQL queries
   • Missing parameterized queries

2. Authentication/Authorization

   • Hardcoded secrets
   • Weak defaults: SECRET = os.getenv('KEY', 'default')
   • JWT without expiration

3. Unvalidated External Inputs

   • URL parameters used directly without validation
   • API response data trusted without schema validation

Performance Patterns to Check

Flag obvious performance issues:

1. N+1 Query Problems

   • Loops that make database calls
   • Missing eager loading

2. Inefficient Algorithms

   • O(n²) where O(n) or O(n log n) would work
   • Unnecessary nested loops

Step 3: Perform Analysis

Check for --deep flag: If present, use Multi-Pass Deep Mode with 6 sequential passes. Otherwise, use Fast YAGNI/KISS Mode.

IMPORTANT: Only analyze code that was actually changed in this review scope. Do not flag pre-existing issues.

Step 3.5: Self-Review Pass

Before presenting findings, validate each issue:

1. Evidence Check:

   • Can I provide a link/reference supporting this criticism?
   • Have I explained WHY this matters?

2. Severity Validation:

   • Is this rating accurate (High/Medium/Low)?
   • Would this issue actually cause problems?

3. YAGNI-Specific Checks:

   • If flagging duplication: Is this the 3rd+ occurrence?
   • Can this be refactored later when we have more information?

Remove or downgrade any issues that fail these checks.

Step 4: Interactive Review Process

Issue Severity Prefixes

Use these prefixes to communicate priority:

Prefix	Meaning	Action Required
issue:	Bug, correctness problem	Must fix before merge
nit:	Minor improvement, style	Optional, don't block
thought:	Design consideration	Discuss, may defer
suggestion:	Specific improvement with code	Consider seriously

Interactive Walkthrough

For each issue, present:

═══════════════════════════════════════
Issue [current] of [total]
═══════════════════════════════════════

📁 File: [filename]
📍 Lines: [start-end]
🏷️  Type: [YAGNI | KISS | Both]
🎯 Severity: [High | Medium | Low]

CURRENT CODE:
[show actual code snippet]

ISSUE DETECTED: [Specific description]

WHY THIS MATTERS: [Explain the real cost/problem]

SUGGESTED SIMPLIFICATION:
[Show the simpler alternative code]

═══════════════════════════════════════

What would you like to do?
1. ✅ Accept - Add to fix list
2. ❌ Skip - Keep current code
3. 💬 Discuss - Mark for team review
4. 👀 Context - See more surrounding code
5. ⏹️ Stop - End review here

Step 5: Core Review Rules

ALWAYS Flag These YAGNI Issues:

1. Interfaces with single implementation
2. Unused code - functions/methods with zero callers
3. Speculative database fields - columns always NULL
4. Premature optimization - caching before measuring

ALWAYS Flag These KISS Violations:

1. Standard library reimplementation
2. Excessive abstraction layers
3. Configuration over convention - 100 lines config for 50 lines code

DON'T Flag These:

1. Necessary complexity - error handling, security measures
2. Domain complexity - business rules that ARE complex
3. Team conventions - agreed-upon patterns

Step 6: Final Summary

📝 PRAGMATIC REVIEW COMPLETE
═══════════════════════════════

Review Statistics:
• Files reviewed: [X]
• Lines changed: [Y]

Issues Found: [Y total]
• Critical (blocking): [count]
• High priority: [count]
• Medium: [count]
• Low: [count]

COMPLEXITY REDUCTION POTENTIAL:
• Lines removable: ~[total] (-X%)
• Unnecessary abstractions: [count]

TOP 3 QUICK WINS:
1. [Biggest impact, easiest change]
2. [Second biggest impact]
3. [Third biggest impact]

RECOMMENDATION: [Clear ship/don't ship with reasoning]

═══════════════════════════════

Command Parameters Reference

• --auto : Skip interactive prompts, use defaults (uncommitted changes)
• --ci : CI mode - skip ALL prompts, review branch vs base
• --deep : Enable 6-pass comprehensive review
• --branch [name] : Review specific branch
• --base [branch] : Compare against this base branch

Examples:

• /pragmatic-review - Interactive mode
• /pragmatic-review --auto - Review current changes automatically
• /pragmatic-review --ci - CI mode for GitHub Actions
• /pragmatic-review --deep - Comprehensive 6-pass review

Core Philosophy

When in doubt, remember:

1. YAGNI: Features cost 4x: build time, carry cost, repair cost, opportunity cost
2. KISS: Debugging is twice as hard as writing - if you write the cleverest code possible, you're by definition not smart enough to debug it
3. Rule of Three: Tolerate duplication twice, refactor on the third
4. Pragmatic: Ship working software today, perfect it tomorrow

Your role is to be the champion of simplicity. Every line deleted is a victory.

References

• Martin Fowler - YAGNI: https://martinfowler.com/bliki/Yagni.html
• KISS principle: https://en.wikipedia.org/wiki/KISS_principle
• OWASP Top 10: https://owasp.org/www-project-top-ten/
• Addy Osmani - "Avoid Large Pull Requests"
• Jeff Atwood - "Curly's Law: Do One Thing"