Pragmatic Code Review: YAGNI & KISS Focus Skill

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:

Try: git rev-parse --verify main
If that fails, try: git rev-parse --verify master
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

Unused abstractions
- Interfaces/protocols with single implementations
- Abstract base classes with one concrete subclass
- Generic types that are always the same
Premature flexibility
- Configuration for things that never change
- Plugin systems with no plugins
- Feature flags that are always on/off
Over-engineering indicators
- Factory classes for simple objects
- Builder patterns for objects with 2-3 fields
- Event systems with single listeners
Speculative code
- "TODO: might need this" comments
- Commented-out code "just in case"
- Unreachable code paths
- Methods that are never called
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
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

Verbose implementations
- Can be reduced by >50% lines
- Reimplements standard library functions
- Complex regex when simple string operations work
Abstraction addiction
- More than 3 levels of inheritance/wrapping
- Interfaces between every layer
Clever code
- Needs extensive comments to explain
- Uses obscure language features unnecessarily
- One-liners that should be 5 clear lines

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:

SQL Injection
- String concatenation in SQL queries
- Missing parameterized queries
Authentication/Authorization
- Hardcoded secrets
- Weak defaults: SECRET = os.getenv('KEY', 'default')
- JWT without expiration
Unvalidated External Inputs
- URL parameters used directly without validation
- API response data trusted without schema validation

Performance Patterns to Check

Flag obvious performance issues:

N+1 Query Problems
- Loops that make database calls
- Missing eager loading
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:

Evidence Check:
- Can I provide a link/reference supporting this criticism?
- Have I explained WHY this matters?
Severity Validation:
- Is this rating accurate (High/Medium/Low)?
- Would this issue actually cause problems?
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:

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

ALWAYS Flag These KISS Violations:

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

DON'T Flag These:

Necessary complexity - error handling, security measures
Domain complexity - business rules that ARE complex
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:

YAGNI: Features cost 4x: build time, carry cost, repair cost, opportunity cost
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
Rule of Three: Tolerate duplication twice, refactor on the third
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"

Agent Skills: Pragmatic Code Review: YAGNI & KISS Focus

Install this agent skill to your local

Skill Files