Test-Driven Development

Indexed Reference Map

• @[SKILL.md#L1-L99] Frontmatter, trigger rules, SOP, output contract.
• @[references/INDEX.md#L1-L19] Reading order and reference inventory.
• @[references/tdd-cycle.md#L1-L14] Red-green-refactor flow and stop conditions.
• @[references/test-design.md#L1-L12] How to design useful tests/probes first.
• @[references/anti-patterns.md#L1-L8] Common mistakes that fake TDD without real evidence.
• @[references/examples.md#L1-L13] Example TDD task shapes.

Scope

• In-scope:
  • Designing and applying a TDD workflow for a feature or bugfix.
  • Writing or specifying tests/probes before code changes.
  • Keeping implementation bounded to what the failing test requires.
• Out-of-scope:
  • Blind coding first and adding tests later.
  • Pure debugging without a reproducible target behavior.
  • Large refactors where no meaningful test seam exists yet.

KB Mode Notes

• Reading order:
  1. references/INDEX.md
  2. references/tdd-cycle.md
  3. references/test-design.md
  4. references/anti-patterns.md
  5. references/examples.md
• Coverage Matrix:
  • Core loop -> tdd-cycle.md
  • Test shaping -> test-design.md
  • Failure modes -> anti-patterns.md
  • Example shapes -> examples.md
• Portability note:
  • “Test” may be a unit test, integration check, scriptable probe, or deterministic reproduction command depending on project constraints.

Trigger Rules

• Positive:
  • User asks for TDD, test-first flow, reproduce bug with a test, or lock expected behavior before implementation.
  • Prompt contains intent like: write test first, TDD this, add failing test, prove the bug first, define expected behavior before patching.
  • A bugfix or feature would benefit from a clear failing proof before code mutation.
• Negative:
  • The task is trivial enough that formal TDD adds no value.
  • The user explicitly wants a quick patch without a prior test artifact.
  • There is no realistic way to create a meaningful deterministic check yet.
• Escalation:
  • If no stable test seam exists, plan the minimal probe/reproduction path first.
  • If test infrastructure is absent, use the lightest reproducible check that still creates evidence.

SOP

1. Define expected behavior
   • State what should happen before writing code.
2. Write the first failing check
   • Use a real test or deterministic probe.
3. Confirm it fails for the right reason
   • Avoid false-red caused by bad setup.
4. Implement the minimum patch
   • Change only what is required to make the failing check pass.
5. Rerun the check
   • Confirm green on the original target.
6. Check adjacent impact
   • Run nearby smoke checks when risk justifies it.
7. Refactor only after green
   • Keep behavior locked while improving code shape.
8. Document the evidence
   • Record red -> green proof and any remaining limitations.

Error Handling

• Failing test not reproducible:
  • Fix the harness/setup before claiming red.
• Test is too broad/flaky:
  • Narrow it to the smallest deterministic behavior.
• User wants refactor during red state:
  • Defer until green unless the test seam itself must be created.
• No test framework available:
  • Use command-level probes or scripted checks as substitute evidence.

Output Contract

• Deliverable:
  • Expected Behavior: target behavior.
  • Failing Check: test/probe written first.
  • Failure Evidence: what proves red.
  • Implementation Scope: minimal patch boundary.
  • Passing Evidence: what proves green.
  • Adjacent Checks: extra verification if run.
  • Remaining Risks: anything still unproven.
• Validation:
  • Must show a real red -> green path, not “I think this would fail.”
• Compliance Verdict:
  • PASS when test-first discipline is preserved; otherwise PARTIAL or FAIL.