---
name: project-test-driven-implementation
description: Use when implementing a PRD Plugin planned task, request, bug fix, behavior change, or refactor before writing implementation code.
---

# Project Test-Driven Implementation

Adapted from Superpowers by Jesse Vincent, MIT licensed:
https://github.com/obra/superpowers

Use this skill to apply Superpowers-style test-driven development while keeping
PRD Plugin project truth, IDs, evidence, and request state intact.

## Iron Law

```text
NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
```

PRD Plugin IDs are non-negotiable. The test and implementation must link back
to the durable project item that justifies the work.

## Rules

- Start from an accepted `REQ-*`, mapped `IMP-TASK-*`, health finding `HLT-*`,
  or explicit user-approved task.
- If no durable source exists and the change affects project truth, create or
  update the appropriate `REQ-*`, `TRK-*`, or `HLT-*` before implementation.
- **Find the existing coverage before you write a new test.** Grep the test
  suite for the symbol, the file, and the behaviour you are about to change
  (`rg "<symbol>" tests/`, then read the module that owns it). If a test
  already asserts this behaviour, **extend or amend it** rather than adding a
  second one beside it. Only write a genuinely new test for genuinely new
  behaviour.
- **Never reuse a test method name inside a class.** Python keeps the last
  definition, so a second `def test_x` in the same class silently discards the
  first — no error, and the reported test count does not drop. Three of these
  were found in the plugin's own suite; two had lost real assertions, so
  coverage had gone *down* while the test count went up. A guard test that
  parses every `test_*.py` and fails on a repeated name is worth carrying in any
  repo with more than a handful of test classes.
- Write the failing test first and run it. Confirm it fails because behavior is
  missing or broken, not because the test is malformed.
- Implement the smallest root-cause change needed to make the test pass.
- Run the focused test, then the relevant broader validation.
- Record durable validation as `EV-*` when claiming completion, acceptance,
  request implementation, or plan completion.
- Update `CHG-*` when project truth, templates, skills, scripts, or user-facing
  behavior changed.
- When implementing a request, update the `REQ-*` status, thread `MSG-*`, and
  `graduated_to` links.
- Do not replace `IMP-TASK-*` IDs with ad hoc checkbox tasks. Checkboxes can be
  execution aids, but durable work keeps PRD Plugin IDs.

## Red-Green-Refactor With PRD Plugin Hooks

1. **RED**: add a minimal failing test linked to the source `REQ-*`,
   `IMP-TASK-*`, or `HLT-*`.
2. **VERIFY RED**: run the exact command and inspect the failure. Scoped, always
   — the one module holding the new test.
3. **GREEN**: implement the smallest fix or feature.
4. **VERIFY GREEN**: run the **scoped** command — the test modules covering the
   files you changed (a source file maps to the test module named for it).
   **The full suite belongs before a commit, not in this loop.** Re-running the
   whole suite after every green step re-tests code you did not touch and buries
   the loop in multi-minute silences; `hooks.test_scope_guard.enabled` will block
   it while nothing is staged and name the scoped command instead.
5. **PERSIST**: update `EV-*`, `CHG-*`, `REQ-*`, `MSG-*`, `TRK-*`, or `HLT-*`
   only where durable project truth changed.
6. **REFACTOR**: clean only after tests pass, preserving the same verification.

## Anchor the ID in Code

Stamp the driving record id (`REQ-*`, `IMP-TASK-*`, `PRD-REQ-*`) in a comment
or docstring at the primary implementation site and in the regression test.
`prd_graph.py` indexes these code anchors (`--anchors <ID>` lists the exact
files and lines), so a feature traces from request/plan to code and back.
One stamp at the load-bearing site beats scattering ids on every line.

## Staleness Coverage

Apply the shared policy in `.prd_plugin/method/staleness-rules.md`.


Before implementing, check whether the source `REQ-*`, `IMP-TASK-*`, `TRK-*`,
or `HLT-*` is stale. Refresh it with current evidence, supersede it, or carry
the stale state forward explicitly before using it as implementation authority.

## Red Flags

- Code was written before the failing test.
- The test passed immediately.
- The implementation has no source ID.
- A request was marked implemented without `graduated_to`.
- Completion was claimed without `EV-*` or fresh command output.
- A test was added after the fix and called TDD.

Stop and repair the workflow before continuing.