Test driven development

Test-Driven Development

Use this skill when code changes should be driven by reproducible behavior rather than guesswork.

Goal

Increase implementation success rate by forcing this order:

1. understand current behavior
2. reproduce the problem or desired behavior
3. write the smallest failing test
4. make the smallest fix
5. rerun the smallest relevant test set
6. broaden validation only after the targeted test passes

Core Rules

1. Reproduce before changing code

Do not start by editing implementation unless the expected behavior is already clear.

First determine:

• what is broken or missing
• how to reproduce it
• what file/function/module is likely involved
• what test mechanism already exists

If no reproduction is possible yet, create one first.

2. Find the existing test entrypoint

Inspect the project and identify:

• test framework
• test command
• test file layout
• package manager or runner
• whether there are targeted test commands already available

Prefer the project’s existing testing conventions.

3. Start with the smallest failing test

Write or update the narrowest test that captures the bug or desired feature.

Prefer:

• one function-level test
• one regression test
• one route/component test
• one CLI invocation test
• one minimal repro script when no framework exists

Avoid starting with the whole suite unless the project is tiny.

4. Make the minimum implementation change

Fix only what the failing test requires first.

Avoid:

• unrelated cleanup
• broad refactors before the failing case passes
• changing multiple subsystems at once
• speculative fixes not backed by the repro

5. Validate in widening circles

After the smallest test passes, widen validation in this order:

1. closest related tests
2. relevant module/package tests
3. full suite if feasible
4. runtime/manual verification if needed

6. Keep evidence visible

When reporting progress, include:

• how the bug/feature was reproduced
• what failing test was added or updated
• what minimal change was made
• what tests were rerun and their outcomes

Minis-Specific Workflow

Shell-first for testing

Use shell commands to:

• inspect project structure
• find test files
• run targeted tests
• run linters or build steps when relevant
• create small repro scripts when no test framework exists

Browser for web verification

For web apps or HTML tools:

• use browser automation to confirm visible behavior
• pair browser verification with code-level tests when possible
• do not rely on visual inspection alone if a real automated test can be added

If there is no test framework

Create the smallest reproducible harness available, for example:

• a minimal Python script with assertions
• a minimal Node script
• a shell script that checks exit code/output
• a tiny HTML/JS repro page

If you must work without a formal test framework, still preserve the TDD order: reproduce -> capture expected behavior -> change code -> rerun repro

Bugfix Pattern

For bugs, follow this sequence:

1. restate the bug clearly
2. reproduce it
3. locate the narrowest failing test surface
4. write a regression test
5. confirm the test fails for the right reason
6. patch the implementation minimally
7. rerun the regression test
8. rerun nearby tests
9. summarize root cause and fix

Feature Pattern

For features, follow this sequence:

1. restate the expected behavior
2. identify existing patterns in the codebase
3. write a test that describes the new behavior
4. confirm the test fails
5. implement the smallest code needed
6. rerun targeted tests
7. broaden validation if needed

Refactor Pattern

For refactors:

1. identify current behavior first
2. ensure behavior is covered by tests
3. add missing characterization tests if needed
4. refactor in small steps
5. rerun tests after each meaningful step

Heuristics

Prefer:

• failing test before fix
• narrow test before broad suite
• regression tests for bugs
• characterization tests before risky refactors
• one hypothesis at a time
• one patch that matches one failing behavior

Be cautious when:

• the bug is not yet reproducible
• multiple failures appear at once
• the codebase has no tests
• the app behavior depends on browser/UI state
• the project’s test command is slow or flaky

Completion Checklist

Before calling the task done, check:

• Is there a reproducible test or repro?
• Did it fail before the fix?
• Does it pass after the fix?
• Were nearby tests rerun?
• Was the fix kept minimal?
• Was any manual/browser verification also needed?
• Is the explanation tied to evidence, not guesswork?

Response Template

• Task type: bugfix / feature / refactor
• Reproduction:
• Smallest failing test:
• Minimal change:
• Validation run:
• Current status:
• Suggested next step:

Example Triggers

• "Implement this feature with TDD."
• "Fix this bug, but write a regression test first."
• "Before changing code, reproduce the issue and add the smallest failing test."
• "Refactor this safely with characterization tests first."
• "Help me raise the success rate of this coding task."