Yagni

yagni

Enforces YAGNI (You Aren't Gonna Need It) and KISS (Keep It Simple, Stupid) principles through structured, non-blocking nudges with severity scoring and real-time detection.

Core Principles

YAGNI — You Aren't Gonna Need It

• Only implement features when actually needed
• Speculative features accumulate technical debt
• "YAGNI violations look smart and prepared. That's why they're dangerous."

KISS — Keep It Simple, Stupid

• Simplest solution that works is usually best
• Complexity is cost, not feature
• Direct code beats clever code

Commands

Pattern Detection

Core Patterns

Enhanced Detection — Complexity Metrics

Code Smell Detection

Design Pattern Library

Patterns have appropriate vs. premature contexts:

Severity Scoring

Severity Calculation

Each violation receives a weighted severity score:

Severity = BaseWeight × ImpactMultiplier × FrequencyFactor

Where:
- BaseWeight: Pattern weight (1-3)
- ImpactMultiplier: Scope of impact (1.0-2.0)
- FrequencyFactor: How often this pattern recurs (1.0-1.5)

Impact Scope Multipliers

Severity Thresholds

Technical Debt Quantification

Estimate refactoring cost in time:

Nudge Format

Standard Nudge

┌─ YAGNI: [pattern] ─────────────────────────────────────
│ Severity: [Low|Medium|High|Critical] (score: N)
│
│ Trigger: [what triggered]
│ Concern: [why it matters]
│ Simpler: [alternative approach]
│
│ Debt Estimate: ~[time] to refactor later
│ Related: complexity-assessment score if available
│
└─ [Dismiss] [Snooze 1h] [Whitelist] [/yagni why]

Minimal Nudge (Relaxed Mode)

YAGNI [pattern]: [one-line concern] → [Dismiss]

When You See a Nudge

Nudges are suggestions, not blocks:

1. Pause — Is the complexity serving the current goal?
2. Consider — Could this be done more directly?
3. Check score — High severity warrants more attention
4. Dismiss if valid — Sometimes abstraction is warranted (document why)

Interactive Controls

Sensitivity Levels

Toggle Mechanism

/yagni on          # Enable detection (default)
/yagni off         # Disable for session
/yagni status      # Show current state

State persists for session only.
Global default: enabled at standard sensitivity.

Project-Specific Overrides

Create .claude/yagni.local.md:

---
# Sensitivity: strict | standard | relaxed
sensitivity: standard

# Patterns to always allow (legitimate uses)
whitelist:
  - "*Factory*"      # DI framework requirement
  - "*Repository*"   # Project architecture standard
  - "Abstract*"      # Base classes for plugin system

# Patterns to always flag (project-specific concerns)
escalate:
  - "*Manager*"      # Team prefers explicit naming
  - "*Helper*"       # Discouraged in this codebase

# Complexity thresholds (override defaults)
thresholds:
  cyclomatic_complexity: 15    # Allow higher for legacy code
  cognitive_complexity: 20
  file_length: 500             # Larger files acceptable

# Ignore paths (auto-generated, vendor code)
ignore:
  - "**/generated/**"
  - "**/vendor/**"
  - "**/*.g.dart"
---

Pattern Whitelisting

Add legitimate patterns interactively:

/yagni whitelist "*Factory*"
> Added *Factory* to .claude/yagni.local.md whitelist
> Reason required: [DI framework requirement]

Hook Integration

PreToolUse Hook (Real-time Detection)

YAGNI detection fires via PreToolUse hooks on Write and Edit operations:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Analyze the file being written/edited for YAGNI violations:\n\n1. Check filename against abstraction patterns\n2. Assess complexity metrics if code is substantial\n3. Look for code smells (god object, feature envy, etc.)\n4. Check against project whitelist in .claude/yagni.local.md\n\nIf violation detected and not whitelisted:\n- Calculate severity score\n- Format structured nudge\n- ALLOW with nudge (non-blocking)\n\nIf no violation or whitelisted: ALLOW silently."
          }
        ]
      }
    ]
  }
}

Hook Behavior

• Non-blocking: Hooks ALLOW the operation but display nudge
• Whitelist-aware: Checks .claude/yagni.local.md before firing
• Severity-gated: In relaxed mode, only fires on High/Critical

Integration with Commit Hooks

Optional pre-commit integration for CI:

# In .husky/pre-commit or similar
# Summarize session YAGNI violations
claude --skill yagni --action summary --format json

Complexity Assessment Integration

YAGNI integrates with the complexity-assessment skill for comprehensive analysis.

Cross-Skill Data Flow

complexity-assessment              yagni
       │                            │
       ├─ Scope score ──────────────┤
       │                            │
       ├─ Risk score ───────────────┤ → Severity multiplier
       │                            │
       └─ Tier (SIMPLE/STANDARD/    │
          COMPLEX) ─────────────────┘ → Sensitivity adjustment

Automatic Sensitivity Adjustment

Linking to Refactoring Guidance

When severity is High or Critical, link to examples:

┌─ YAGNI: abstraction ──────────────────────────────────
│ ...
│ Refactoring Guide: skills/yagni/examples/simpler-paths.md#abstraction-creep
└─────────────────────────────────────────────────────────

contextd Integration (Optional)

When contextd MCP is available, YAGNI learns from project history.

Recording Violations

mcp__contextd__memory_record(
  project_id: "<project>",
  title: "YAGNI: <pattern> in <filename>",
  content: "Pattern: <pattern>. Severity: <score>. Trigger: <trigger>.
            Dismissed: <yes/no>. Reason: <user reason if dismissed>.",
  outcome: "<dismissed|addressed|ignored>",
  tags: ["yagni", "<pattern>", "<severity-level>"]
)

Tracking False Positives

# When user marks nudge as false positive
mcp__contextd__memory_record(
  project_id: "<project>",
  title: "YAGNI False Positive: <pattern>",
  content: "Pattern <pattern> on <filename> was false positive.
            User reason: <reason>. Consider adding to whitelist.",
  outcome: "false-positive",
  tags: ["yagni", "false-positive", "<pattern>"]
)

Learning Project Patterns

Query past violations to improve detection:

# Before firing nudge, check history
mcp__contextd__memory_search(
  project_id: "<project>",
  query: "yagni false-positive <pattern>",
  limit: 5
)

# If pattern has high false-positive rate for this project,
# auto-suggest adding to whitelist

Session Summary

At session end (or on /yagni dashboard):

YAGNI Session Summary
├─ Violations detected: 7
├─ Dismissed: 3 (reasons recorded)
├─ Addressed: 2
├─ Ignored: 2
├─ False positives: 1 (whitelist suggested)
├─ Total debt estimate: ~4 hours
└─ Patterns: abstraction (3), scope-creep (2), config-addiction (2)

Trend: abstraction violations up 20% from last 5 sessions

Technical Debt Dashboard

View with /yagni dashboard:

┌─ Technical Debt Dashboard ──────────────────────────────
│
│ Current Session
│ ├─ Active violations: 3
│ ├─ Estimated debt: ~2.5 hours
│ └─ Highest severity: Medium (score 5)
│
│ Project History (last 30 days)
│ ├─ Total violations: 47
│ ├─ Addressed: 31 (66%)
│ ├─ Accumulated debt: ~18 hours
│ └─ Top patterns: abstraction (18), scope-creep (12)
│
│ Recommendations
│ ├─ Consider whitelisting: *Repository* (8 false positives)
│ ├─ Escalate for review: payment-service.ts (Critical)
│ └─ Schedule debt paydown: ~4 hours/week to stay current
│
└─────────────────────────────────────────────────────────

Configuration

Project Override (.claude/yagni.local.md)

Full configuration example:

---
# Core settings
sensitivity: standard    # strict | standard | relaxed
enabled: true           # Master toggle

# Pattern configuration
whitelist:
  - "*Factory*"         # Legitimate DI framework
  - "*Repository*"      # Project standard

escalate:
  - "*Manager*"         # Discouraged naming

# Threshold overrides
thresholds:
  cyclomatic_complexity: 15
  cognitive_complexity: 20
  nesting_depth: 5
  parameter_count: 6
  file_length: 400
  method_count: 25

# Ignore paths
ignore:
  - "**/generated/**"
  - "**/vendor/**"
  - "**/migrations/**"
  - "**/*.generated.*"

# contextd integration
contextd:
  record_violations: true
  track_false_positives: true
  learn_patterns: true
---

Red Flags

• Abstractions before 2+ concrete uses
• Configuration for one-place behavior
• Plugin systems for single implementations
• Optimizing before profiling proves need
• "Future-proofing" against non-existent requirements
• Cyclomatic complexity >10 without tests
• God objects with 10+ dependencies
• Methods >20 lines without extraction

The Simple Test

1. What's the simplest thing that works? — Start there
2. Solving today's problem or tomorrow's guess? — Solve today's
3. Hard to delete if requirements change? — Too coupled
4. New team member understand in 5 minutes? — If not, simplify
5. Does complexity score justify the pattern? — Check metrics

Integration Points

Troubleshooting

Converted and distributed by TomeVault — claim your Tome and manage your conversions.