# When Is the Test-Driven-Development Skill Mandatory in Superpowers?

> Master test-driven development in obra/superpowers when adding or changing code. Ensure failing tests precede implementation and verify red/green states for robust development.

- Repository: [Jesse Vincent/superpowers](https://github.com/obra/superpowers)
- Tags: best-practices
- Published: 2026-02-16

---

**The test-driven-development skill is mandatory whenever you add or change production code in the obra/superpowers repository, requiring a failing test before any implementation and verification of both red and green states.**

The **obra/superpowers** repository enforces strict test-driven-development (TDD) protocols through its skill system. According to the source code in [`skills/test-driven-development/SKILL.md`](https://github.com/obra/superpowers/blob/main/skills/test-driven-development/SKILL.md), the TDD skill activates automatically and becomes non-optional the moment you touch production code.

## Mandatory Scope of the Test-Driven-Development Skill

The TDD skill applies to **all** production code modifications without exception. The skill definition explicitly scopes mandatory usage to any activity that changes system behavior.

### Production Code Changes

According to lines 18-22 in [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md), you must apply the TDD cycle when:

- Adding **new features**
- Fixing **bugs**
- Performing **refactoring**
- Making any **behavior change**

The rule is absolute: if the production code changes, the TDD skill is mandatory.

### The Iron Law Constraint

The source code defines an "Iron Law" at lines 31-35: **"NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST"**. This constraint is hard-coded into the skill logic. You cannot write implementation code until a test exists that fails because the feature is missing.

## Non-Negotiable Verification Steps

The TDD skill mandates specific verification checkpoints that you cannot skip. The [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) file marks these steps explicitly as **MANDATORY** in the source documentation.

### RED Verification

Before writing any implementation, you must complete the **RED** phase. Lines 13-15 in [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) require you to:

1. Write the test
2. Run the test suite
3. **Watch the test fail**

Skipping the RED verification constitutes a rule violation. The test must fail for the correct reason—demonstrating that the feature is genuinely missing.

### GREEN Verification

After implementing the minimal code to satisfy the test, you must complete the **GREEN** phase. According to lines 70-73 in [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md), you must:

1. Run the test suite
2. **Watch the test pass**
3. Ensure the entire suite remains green

This verification is mandatory. You cannot proceed to refactoring or additional features until the GREEN checkpoint confirms the implementation works.

## Exceptions and Edge Cases

The TDD skill allows extremely limited exceptions, but these require explicit human approval rather than automatic exemption.

### Prototypes and Generated Code

Lines 24-28 in [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) mention potential exemptions for:

- **Throw-away prototypes**
- **Generated code**
- **Configuration files**

However, these are **not** automatic exceptions. The source code states you must **ask your human partner** for explicit approval before skipping TDD for these items. Without that approval, the skill remains mandatory.

## Practical Implementation Example

The following example demonstrates the mandatory TDD workflow using the actual skill requirements.

### RED Phase – Mandatory Failing Test

Create the test file first. No implementation code may exist before this step.

```typescript
// tests/retryOperation.test.ts
test('retries a failing operation three times', async () => {
  let attempts = 0;
  const flaky = () => {
    attempts++;
    if (attempts < 3) throw new Error('still failing');
    return 'ok';
  };

  const result = await retryOperation(flaky);
  expect(result).toBe('ok');
  expect(attempts).toBe(3);
});

```

Run the test suite and **verify it fails** (mandatory RED verification):

```bash
npm test

# Expected: FAIL - retryOperation is not defined

```

### GREEN Phase – Minimal Implementation

Write only enough code to make the test pass.

```typescript
// src/retryOperation.ts
export 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');
}

```

Run the test suite and **verify it passes** (mandatory GREEN verification):

```bash
npm test

# Expected: PASS

```

### REFACTOR Phase – Clean While Green

With the mandatory verifications complete, you may now refactor.

```typescript
// src/retryOperation.ts (refactored)
export async function retryOperation<T>(
  fn: () => Promise<T>, 
  maxAttempts = 3
): Promise<T> {
  let attempt = 0;
  while (true) {
    try {
      return await fn();
    } catch (e) {
      if (++attempt >= maxAttempts) throw e;
    }
  }
}

```

The test suite must remain green after refactoring.

## Summary

- The **test-driven-development skill** is mandatory for **all** production code changes in obra/superpowers, including new features, bug fixes, and refactoring.
- The **Iron Law** prohibits writing production code without a failing test first, as defined in [`skills/test-driven-development/SKILL.md`](https://github.com/obra/superpowers/blob/main/skills/test-driven-development/SKILL.md) lines 31-35.
- **RED verification** (watching the test fail) and **GREEN verification** (watching the test pass) are explicitly marked as **MANDATORY** in the skill definition.
- Exceptions for prototypes or generated code require **explicit human approval**; they are not automatic exemptions.

## Frequently Asked Questions

### Is the test-driven-development skill mandatory for documentation changes?

No. According to [`skills/test-driven-development/SKILL.md`](https://github.com/obra/superpowers/blob/main/skills/test-driven-development/SKILL.md), the mandatory scope applies specifically to **production code** changes. Documentation updates, README edits, or comment-only modifications do not trigger the TDD skill requirements, provided they do not alter executable behavior.

### Can I skip the RED verification if I am certain the test will fail?

No. Lines 13-15 in [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) explicitly mark the RED verification as **MANDATORY**. You must run the test suite and observe the failure, even if you are confident in the test logic. This ensures the test fails for the correct reason and validates the test setup.

### What happens if I write production code before writing a test?

This violates the **Iron Law** defined at lines 31-35 in [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md): "NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST." The skill engine in [`lib/skills-core.js`](https://github.com/obra/superpowers/blob/main/lib/skills-core.js) treats this as a rule violation. You must discard the implementation, write the failing test, verify the RED state, and then rewrite the minimal code to pass.

### Are configuration files exempt from the TDD skill?

Only with explicit human approval. Lines 24-28 in [`SKILL.md`](https://github.com/obra/superpowers/blob/main/SKILL.md) mention that "throw-away prototypes, generated code, or configuration files" might be exempt, but emphasize that you must **ask your human partner** for approval. Without that explicit permission, the TDD skill remains mandatory for all file modifications.