> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/obra/superpowers/llms.txt
> Use this file to discover all available pages before exploring further.

# Philosophy & Principles

> The four core principles that make Superpowers enforce better development practices

## Overview

Superpowers is built on four core principles that transform how AI coding agents work. These aren't just guidelines - they're **enforced by the skills system**.

From the README:

<CardGroup cols={2}>
  <Card title="Test-Driven Development" icon="flask">
    Write tests first, always
  </Card>

  <Card title="Systematic over ad-hoc" icon="diagram-project">
    Process over guessing
  </Card>

  <Card title="Complexity reduction" icon="minimize">
    Simplicity as primary goal
  </Card>

  <Card title="Evidence over claims" icon="check-double">
    Verify before declaring success
  </Card>
</CardGroup>

## Principle 1: Test-Driven Development

### The Philosophy

From `skills/test-driven-development/SKILL.md:12-14`:

<Note>
  **Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing.

  **Violating the letter of the rules is violating the spirit of the rules.**
</Note>

TDD isn't just about writing tests - it's about **proving your tests work** before trusting them.

### Why It Matters

#### The "Tests After" Trap

From `skills/test-driven-development/SKILL.md:207-225`:

<Warning>
  **"I'll write tests after to verify it works"**

  Tests written after code pass immediately. Passing immediately proves nothing:

  * Might test wrong thing
  * Might test implementation, not behavior
  * Might miss edge cases you forgot
  * You never saw it catch the bug

  Test-first forces you to see the test fail, proving it actually tests something.
</Warning>

#### Tests vs. Manual Testing

<Accordion title="Why Manual Testing Isn't Enough">
  From `skills/test-driven-development/SKILL.md:217-226`:

  **"I already manually tested all the edge cases"**

  Manual testing is ad-hoc. You think you tested everything but:

  * No record of what you tested
  * Can't re-run when code changes
  * Easy to forget cases under pressure
  * "It worked when I tried it" ≠ comprehensive

  Automated tests are systematic. They run the same way every time.
</Accordion>

### How Superpowers Enforces It

The `test-driven-development` skill enforces the RED-GREEN-REFACTOR cycle:

```mermaid theme={null}
graph LR
    A[RED: Write test] --> B[Verify fails]
    B --> C[GREEN: Minimal code]
    C --> D[Verify passes]
    D --> E[REFACTOR: Clean up]
    E --> A
    
    style A fill:#ffcccc
    style C fill:#ccffcc
    style E fill:#ccccff
```

From `skills/test-driven-development/SKILL.md:33-45`:

<Warning>
  ```
  NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
  ```

  Write code before the test? **Delete it. Start over.**

  **No exceptions:**

  * Don't keep it as "reference"
  * Don't "adapt" it while writing tests
  * Don't look at it
  * Delete means delete
</Warning>

### Common Rationalizations (And Why They're Wrong)

From `skills/test-driven-development/SKILL.md:256-270`:

| Excuse                           | Reality                                                                 |
| -------------------------------- | ----------------------------------------------------------------------- |
| "Too simple to test"             | Simple code breaks. Test takes 30 seconds.                              |
| "I'll test after"                | Tests passing immediately prove nothing.                                |
| "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
| "Already manually tested"        | Ad-hoc ≠ systematic. No record, can't re-run.                           |
| "Deleting X hours is wasteful"   | Sunk cost fallacy. Keeping unverified code is technical debt.           |
| "Need to explore first"          | Fine. Throw away exploration, start with TDD.                           |
| "TDD will slow me down"          | TDD faster than debugging. Pragmatic = test-first.                      |

### The Pragmatic Argument

From `skills/test-driven-development/SKILL.md:236-244`:

<Info>
  **"TDD is dogmatic, being pragmatic means adapting"**

  TDD IS pragmatic:

  * Finds bugs before commit (faster than debugging after)
  * Prevents regressions (tests catch breaks immediately)
  * Documents behavior (tests show how to use code)
  * Enables refactoring (change freely, tests catch breaks)

  "Pragmatic" shortcuts = debugging in production = slower.
</Info>

## Principle 2: Systematic Over Ad-Hoc

### The Philosophy

Ad-hoc development is guessing. Systematic development is **following a proven process**.

From `skills/using-superpowers/SKILL.md:7-11`:

<Warning>
  IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.

  This is not negotiable. This is not optional. You cannot rationalize your way out of this.
</Warning>

### How It Contrasts With Typical Development

<Accordion title="Ad-Hoc vs. Systematic Development">
  **Typical Ad-Hoc Development:**

  ```
  User: Add OAuth to the app
  Agent: Sure! *immediately starts writing code*
  Agent: *30 minutes later* Done! Here's the implementation.
  User: Wait, I wanted Google AND GitHub support
  Agent: Oh, let me refactor... *another hour*
  User: The session handling is broken
  Agent: Let me debug... *finds no tests to verify behavior*
  ```

  **Superpowers Systematic Development:**

  ```
  User: Add OAuth to the app
  Agent: *invokes brainstorming skill*
  Agent: Which providers do you need?
  User: Google and GitHub
  Agent: *asks about session management, security requirements*
  Agent: *proposes 3 approaches with trade-offs*
  Agent: *presents complete design in sections*
  User: Looks good!
  Agent: *creates git worktree, writes detailed plan*
  Agent: *dispatches subagents with TDD enforcement*
  Agent: *two-stage review catches issues early*
  Agent: All done! 8 new tests, all passing.
  ```

  **Result:**

  * Ad-hoc: 2+ hours, broken features, no tests, frustrated user
  * Systematic: 2 hours, working features, full test coverage, validated design
</Accordion>

### Red Flags of Ad-Hoc Thinking

From `skills/using-superpowers/SKILL.md:56-73`:

| Thought                          | Why It's Ad-Hoc                 | Systematic Alternative             |
| -------------------------------- | ------------------------------- | ---------------------------------- |
| "This is just a simple question" | Assumes context, skips planning | Check for skills before responding |
| "Let me explore first"           | Undirected wandering            | Skills tell you HOW to explore     |
| "I'll just do this one thing"    | One thing becomes many          | Check skills BEFORE doing anything |
| "This feels productive"          | Activity ≠ progress             | Disciplined action via skills      |
| "The skill is overkill"          | Assumes simplicity lasts        | Simple things become complex       |

### The Brainstorming Anti-Pattern

From `skills/brainstorming/SKILL.md:18-20`:

<Warning>
  **Anti-Pattern: "This Is Too Simple To Need A Design"**

  Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work.
</Warning>

### How Superpowers Enforces It

<Steps>
  <Step title="Skill Check First">
    From `skills/using-superpowers/SKILL.md:23-24`:

    "Invoke relevant or requested skills BEFORE any response or action. Even a 1% chance a skill might apply means that you should invoke the skill to check."
  </Step>

  <Step title="Mandatory Workflows">
    From README line 94:

    "The agent checks for relevant skills before any task. Mandatory workflows, not suggestions."
  </Step>

  <Step title="Hard Gates">
    Skills contain `<HARD-GATE>` sections that prevent skipping critical steps.

    From `skills/brainstorming/SKILL.md:14-16`:

    ```
    Do NOT invoke any implementation skill, write any code, scaffold any 
    project, or take any implementation action until you have presented 
    a design and the user has approved it.
    ```
  </Step>
</Steps>

## Principle 3: Complexity Reduction

### The Philosophy

Simplicity isn't about doing less - it's about **doing exactly what's needed and nothing more**.

### YAGNI: You Aren't Gonna Need It

From `skills/brainstorming/SKILL.md:92-94`:

One of the key principles emphasized in brainstorming:

* **YAGNI ruthlessly** - Remove unnecessary features from all designs

And from the README (line 11):

> It emphasizes true red/green TDD, YAGNI (You Aren't Gonna Need It), and DRY.

### Minimal Implementation

From `skills/test-driven-development/SKILL.md:132-166`:

<Accordion title="Good vs. Over-Engineered Code">
  **Good (Minimal):**

  ```typescript theme={null}
  async function retryOperation<T>(fn: () => Promise<T>): Promise<T> {
    for (let i = 0; i < 3; i++) {
      try {
        return await fn();
      } catch (e) {
        if (i === 2) throw e;
      }
    }
    throw new Error('unreachable');
  }
  ```

  Just enough to pass the test.

  **Bad (Over-Engineered):**

  ```typescript theme={null}
  async function retryOperation<T>(
    fn: () => Promise<T>,
    options?: {
      maxRetries?: number;
      backoff?: 'linear' | 'exponential';
      onRetry?: (attempt: number) => void;
    }
  ): Promise<T> {
    // YAGNI - all this complexity wasn't tested
  }
  ```

  The test only needed 3 retries. Don't add:

  * Configurable retry counts
  * Backoff strategies
  * Retry callbacks

  **Add them WHEN you need them, with tests first.**
</Accordion>

### Bite-Sized Tasks

From `skills/writing-plans/SKILL.md:20-27`:

Complexity reduction extends to planning:

<Note>
  **Each step is one action (2-5 minutes):**

  * "Write the failing test" - step
  * "Run it to make sure it fails" - step
  * "Implement the minimal code to make the test pass" - step
  * "Run the tests and make sure they pass" - step
  * "Commit" - step

  Breaking work into tiny pieces reduces cognitive load and makes progress visible.
</Note>

### How Superpowers Enforces It

<CardGroup cols={2}>
  <Card title="GREEN Step" icon="code">
    TDD skill mandates: "Write simplest code to pass the test. Don't add features, refactor other code, or 'improve' beyond the test."
  </Card>

  <Card title="YAGNI in Design" icon="scissors">
    Brainstorming skill emphasizes: "YAGNI ruthlessly - Remove unnecessary features from all designs"
  </Card>

  <Card title="Granular Plans" icon="list">
    Writing-plans skill requires bite-sized tasks (2-5 minutes each)
  </Card>

  <Card title="Spec Compliance Review" icon="clipboard-check">
    Subagent-driven development checks for: "Nothing extra was added (YAGNI)"
  </Card>
</CardGroup>

## Principle 4: Evidence Over Claims

### The Philosophy

**Don't declare success until you've proven it.**

From `skills/test-driven-development/SKILL.md:113-125`:

<Warning>
  ### Verify RED - Watch It Fail

  **MANDATORY. Never skip.**

  Confirm:

  * Test fails (not errors)
  * Failure message is expected
  * Fails because feature missing (not typos)

  **Test passes?** You're testing existing behavior. Fix test.

  **Test errors?** Fix error, re-run until it fails correctly.
</Warning>

And:

<Warning>
  ### Verify GREEN - Watch It Pass

  **MANDATORY.**

  Confirm:

  * Test passes
  * Other tests still pass
  * Output pristine (no errors, warnings)
</Warning>

### The Verification Loop

Every phase includes verification:

<Steps>
  <Step title="Worktree Setup">
    From `skills/using-git-worktrees/SKILL.md:121-134`:

    Run tests to ensure worktree starts clean. If tests fail, report failures and ask whether to proceed.
  </Step>

  <Step title="Implementation">
    TDD cycle requires watching tests fail, then watching them pass.
  </Step>

  <Step title="Code Review">
    Two-stage review: spec compliance, then code quality.
  </Step>

  <Step title="Branch Completion">
    From `skills/finishing-a-development-branch/SKILL.md:18-36`:

    Verify tests pass before presenting merge options. If tests fail, cannot proceed.
  </Step>
</Steps>

### Why "It Works For Me" Isn't Enough

From `skills/test-driven-development/SKILL.md:218-226`:

<Info>
  **"I already manually tested all the edge cases"**

  Manual testing is ad-hoc. You think you tested everything but:

  * No record of what you tested
  * Can't re-run when code changes
  * Easy to forget cases under pressure
  * "It worked when I tried it" ≠ comprehensive

  Automated tests are systematic. They run the same way every time.
</Info>

### The Verification Checklist

From `skills/test-driven-development/SKILL.md:327-340`:

Before marking work complete:

* [ ] Every new function/method has a test
* [ ] Watched each test fail before implementing
* [ ] Each test failed for expected reason (feature missing, not typo)
* [ ] Wrote minimal code to pass each test
* [ ] All tests pass
* [ ] Output pristine (no errors, warnings)
* [ ] Tests use real code (mocks only if unavoidable)
* [ ] Edge cases and errors covered

**Can't check all boxes? You skipped TDD. Start over.**

### How Superpowers Enforces It

<CardGroup cols={2}>
  <Card title="Mandatory Test Verification" icon="vial">
    TDD skill requires watching tests fail AND pass. No skipping.
  </Card>

  <Card title="Clean Baselines" icon="check">
    Git worktrees skill verifies tests pass before starting work.
  </Card>

  <Card title="Two-Stage Review" icon="magnifying-glass">
    Spec compliance review proves it does what the plan says. Code quality review proves it's well-built.
  </Card>

  <Card title="Final Verification" icon="flag-checkered">
    Finishing branch skill runs full test suite before merge/PR.
  </Card>
</CardGroup>

## How These Principles Work Together

The four principles create a **reinforcing system**:

```mermaid theme={null}
graph TD
    A[TDD] --> B[Evidence]
    B --> C[Complexity Reduction]
    C --> D[Systematic Process]
    D --> A
    
    A -.->|Tests prove code works| B
    B -.->|Verification prevents over-building| C  
    C -.->|Simplicity enables process| D
    D -.->|Process enforces TDD| A
    
    style A fill:#ffe1e1
    style B fill:#e1fff5
    style C fill:#fff4e1
    style D fill:#e1f5ff
```

<Steps>
  <Step title="TDD provides evidence">
    Watching tests fail and pass proves the code works and the tests are valid.
  </Step>

  <Step title="Evidence prevents complexity">
    When you must verify everything, you stop adding unneeded features.
  </Step>

  <Step title="Simplicity enables process">
    Bite-sized tasks and minimal implementations make systematic workflows feasible.
  </Step>

  <Step title="Process enforces TDD">
    Skills contain hard gates that prevent skipping the RED-GREEN-REFACTOR cycle.
  </Step>
</Steps>

## Real-World Impact

### Before Superpowers

<Accordion title="Typical AI Agent Development">
  **User:** "Add a feature to export user data"

  **Agent:**

  * Immediately starts writing code
  * Adds export to CSV, JSON, XML ("might need them")
  * No tests ("I'll add them later")
  * Doesn't ask about requirements
  * 200 lines of code, 3 edge cases missed
  * User discovers bugs in production
  * No systematic way to prevent regressions

  **Time:** 30 minutes\
  **Quality:** Broken, untested, over-engineered\
  **User Satisfaction:** Low (fixing bugs in production)
</Accordion>

### With Superpowers

<Accordion title="Systematic Superpowers Development">
  **User:** "Add a feature to export user data"

  **Agent:**

  1. **Brainstorming** (10 min)
     * "What format do you need?" → "Just CSV for now"
     * "What fields should be included?" → "Email, name, created date"
     * Proposes 3 approaches, recommends standard CSV library
     * Presents design covering data selection, formatting, error handling
     * Saves design doc

  2. **Git Worktree** (2 min)
     * Creates isolated workspace
     * Verifies clean test baseline

  3. **Writing Plan** (5 min)
     * Breaks into 4 bite-sized tasks
     * Each task has: test → verify fail → implement → verify pass → commit

  4. **Subagent-Driven Development** (20 min)
     * Fresh subagent per task
     * TDD enforced: watched each test fail, then pass
     * Two-stage review after each task
     * 4 new tests, all passing

  5. **Finishing Branch** (3 min)
     * Verifies all tests pass
     * Creates PR with summary

  **Time:** 40 minutes\
  **Quality:** Working, tested (4 tests), exactly what's needed\
  **User Satisfaction:** High (works correctly, easy to extend later)
</Accordion>

### The Difference

<CardGroup cols={2}>
  <Card title="10 Minutes Slower" icon="clock">
    But saves hours of debugging and fixing production issues
  </Card>

  <Card title="Tests Included" icon="check-double">
    Not "I'll add them later" (which never happens)
  </Card>

  <Card title="Right Feature Built" icon="bullseye">
    CSV only, not CSV + JSON + XML you don't need
  </Card>

  <Card title="Proven Quality" icon="shield-check">
    Tests watched failing and passing - evidence it works
  </Card>
</CardGroup>

## Common Objections

### "This will slow me down"

From `skills/test-driven-development/SKILL.md:268`:

<Info>
  TDD faster than debugging. Pragmatic = test-first.

  Yes, Superpowers adds 10-15 minutes upfront for brainstorming and planning. But it saves hours of:

  * Debugging issues that could have been caught by tests
  * Refactoring over-engineered solutions
  * Re-implementing features that didn't match requirements
  * Fixing regressions because there were no tests
</Info>

### "The process feels rigid"

From `skills/using-superpowers/SKILL.md:86-91`:

<Note>
  **Rigid** (TDD, debugging): Follow exactly. Don't adapt away discipline.

  **Flexible** (patterns): Adapt principles to context.

  The skill itself tells you which. Rigidity exists **only where it prevents common mistakes**.
</Note>

### "I know what I'm doing, I don't need a checklist"

From `skills/using-superpowers/SKILL.md:67-69`:

<Warning>
  | Thought                  | Reality                                           |
  | ------------------------ | ------------------------------------------------- |
  | "I know what that means" | Knowing the concept ≠ using the skill. Invoke it. |
  | "I remember this skill"  | Skills evolve. Read current version.              |

  Even experts benefit from checklists. Ask any surgeon or pilot.
</Warning>

## Key Takeaways

<CardGroup cols={2}>
  <Card title="TDD Proves Tests Work" icon="flask">
    Watching tests fail first proves they actually test something. Tests-after prove nothing.
  </Card>

  <Card title="Process Beats Guessing" icon="route">
    Systematic workflows prevent wasted work from unexamined assumptions.
  </Card>

  <Card title="Simple Beats Clever" icon="lightbulb">
    Build exactly what's needed. Add complexity WHEN needed, with tests first.
  </Card>

  <Card title="Show, Don't Tell" icon="magnifying-glass">
    Verify every claim. Clean baselines, test verification, code review.
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Skills Overview" href="/concepts/overview" icon="grid">
    Learn how the skills system enforces these principles
  </Card>

  <Card title="Workflow" href="/concepts/workflow" icon="diagram-project">
    See the complete development process in action
  </Card>

  <Card title="Get Started" href="/quickstart" icon="rocket">
    Install Superpowers and start using it
  </Card>
</CardGroup>