| name | spectre-tdd |
| description | Execute implementation via strict red/green/refactor — derive behavioral Test Opportunities, write a happy/failure baseline plus risk-justified cases, confirm RED before production code, then ship minimal GREEN code. Trigger for TDD, failing-test-first, or RED-GREEN-REFACTOR execution; not test auditing/planning (use spectre-test). |
tdd
Implement assigned behavior through strict RED → GREEN → REFACTOR. Outcome: tasks done with happy + failure tests passing and only test-forced production code shipped.
Inputs
$ARGUMENTS or thread context — the assigned implementation task(s). If no clear task, stop and ask.- The task's acceptance criteria / artifact, if one exists.
Working Set (late-bound — read at run-time, never inline)
- Target behavior, acceptance criteria, and the smallest affected code/test files.
- Narrow test/lint commands for those files only (
--testPathPattern, --findRelatedTests, per-file lint, or equivalent).
- Existing test helpers, fixtures, stubs, fake timers, seeded-RNG patterns.
Outputs + DONE
- A todo list with one cycle per Test Opportunity:
RED behavioral cases → GREEN minimal impl → REFACTOR → COMMIT.
- The implementation diff, focused tests, and (optional) conventional commit
feat({task}): description.
- A completion report: Summary (tasks done, ✅ happy / ✅ failure test status, files modified); Artifacts (helpers/mocks/fixtures); API Surface (new/modified exports + signatures); Patterns; Deferred coverage gaps.
DONE when: every Test Opportunity has a representative happy-path and primary-failure baseline unless the behavior genuinely supports only one; distinct requirement/boundary/regression/material-risk cases are also covered; every new test was observed failing for the expected reason before satisfying implementation; minimal production code makes focused tests pass; refactors stay green; every new observable behavior or nontrivial exported contract is tested; and focused tests + relevant lint pass.
Method / guardrails
- Iron Law — YOU MUST confirm RED before GREEN. No production code before a failing test. If code was written first, delete it and restart from the tests — do not keep it as reference, do not adapt it.
- A Test Opportunity is the smallest externally meaningful behavior or contract: a route, bug fix, acceptance criterion, public boundary, or independently risky logic. Private helpers are normally covered through observable behavior unless they contain independently risky logic.
- Start each opportunity with one representative happy-path and one primary-failure test. Add another behavioral case only for a distinct requirement, public/contract boundary, credible regression, or materially different risk. Reject duplicated assertions, implementation-detail tests, and unjustified combinatorial matrices.
- Run the narrowest command and confirm every new test fails (not errors) for the missing behavior before production code satisfies it. A test that passes immediately covers existing behavior—fix it or choose uncovered behavior.
- GREEN = the least code to pass the focused tests: no extra branches, params, dependencies, or abstractions unless a test forces them or ≥2 call sites exist (YAGNI).
- Refactor only while green, and only for duplication ≥3 or a material readability gain; if a refactor breaks tests, revert it.
- Resolve lint pressure in order: guard clauses / split compounds → tiny same-file helpers → file constants → orchestrator + helpers → same-directory helper module only if still failing.
- Keep execution scoped — never run repo-wide tests when a focused command exists.
- Prefer the repo's existing anti-flake patterns: fake timers, stubs, seeded RNG, deterministic fixtures.
Handoff
Return the completion report inline with the exact commands run and pass/fail evidence — no scratch files. With --orchestrated, return to the caller without user-facing Next Steps. Standalone: recommend spectre-prove for completed user-observable behavior, spectre-test only for a concrete remaining coverage gap, or spectre-clean only when proof is explicitly deferred. Emit one primary route tied to the observed result.
Escalate-If
- The assigned task or its acceptance criteria are unclear → stop and ask.
- You cannot make a meaningful RED test fail for the expected reason.
- The focused test command cannot be isolated to the changed files.
- Test setup dwarfs the behavior under test → the design is too coupled; simplify the interface (or ask) before continuing.
