atomic-tdd

name

atomic-tdd

description

Test-first discipline. Auto-triggers on "let's implement X", "add feature Y", "fix bug Z", "write a test for", "implement", "build out", and similar pre-code-change phrases. Iron rule: failing test exists before production code. Skip only for pure docs/config changes with an explicit "skipped because:" note. Explicit invocation: /atomic-tdd. Boundary with atomic-debug: this skill owns writing or changing code — new behavior, or a fix whose root cause is already understood. Diagnosing why something is broken (unknown cause) is atomic-debug's job; debug to the root cause first, then return here to write the fix test-first.

Test first. Watch it fail. Write minimal code. Watch it pass. Refactor green.

Auto-trigger on:

• "let's implement X", "add feature Y", "build out Z"
• "fix bug", "patch the regression"
• "write tests for", "write a test for"
• "make the code do X"
• Any pre-implementation language for behavior changes

Explicit: /atomic-tdd.

The iron law

Write the failing test before production code. Why: tests written after implementation mirror what the code does, not what it should do. Tests-first are specifications; tests-after are tautologies.

Wrote code before a failing test? Delete it. Start over. Why: keeping existing code as reference biases the test toward the implementation rather than the intent.

The cycle

Step	Action	Verify
RED	Write one minimal failing test	Run it. Must fail for the right reason — feature missing, not a typo. If it passes immediately, the test is wrong. Fix the test.
GREEN	Write the smallest code that makes the test pass	Run all tests. Must be green. No "while I'm here" extras.
REFACTOR	Clean up only after green	Re-run. Must stay green. No behavior changes.

Repeat for the next behavior.

Required for

• New features — any new behavior
• Bug fixes — test reproduces the bug first, then fix
• Refactoring — existing tests must stay green; if none exist, add one first
• Behavior changes

Skip rules

TDD doesn't apply to these cases. Each skip requires an explicit skipped because: <reason> note in the response.

Skip case	Example
Pure docs / Markdown / comment-only edits	Updating README, adding a JSDoc
Pure config / .env / non-executable file edits	Changing a JSON config, updating an env var
Generated code	Regenerated from a schema or spec, not hand-written
Throwaway prototypes the user explicitly flagged as throwaway	"Just spike this, we'll throw it away"

Skipping silently = violation.

Discipline reminders

The test always comes first. These situations tempt shortcuts — resist them:

• Code already written without a test → delete it, write the test first, then reimplement. Keeping existing code as reference biases the test toward the implementation rather than the intent.
• "Too simple to need a test" → simple code deserves a simple test. Write it.
• Tests-after vs tests-first are fundamentally different: tests-first answer "what should this do?", tests-after answer "what does this do?"

Good test characteristics

Quality	Yes	No
Minimal	One behavior per test	"and" in the name → split it
Clear	Name describes the behavior	test1, it works
Real	Real inputs, real outputs	Asserts on mocks (tests the mock, not the code)

Purpose of tests

Tests prove the feature works for real users. They are not the goal — they are evidence.

• Passing tests are not success. Correct behavior is success. If the feature works wrong but tests pass, the tests are wrong.
• A test that cannot fail when business logic changes is dead weight. Every test encodes an intention: "if this breaks, something the user cares about is wrong."
• Do not write tests to satisfy coverage metrics or make CI green. Write tests that would catch a regression a user would notice.
• Tests-first answer "what should this do?" — they encode intent before implementation exists. This is why TDD works: the test is a specification, not a verification of existing code.

Boundaries

• Bug fix: the failing test must reproduce the bug as reported. If you can't write a test that fails on current code, you don't understand the bug yet — switch to atomic-debug first. Why: a test that doesn't match the reported symptom may pass after the fix while the real bug persists.
• atomic-tdd + atomic-verify: both fire independently. atomic-tdd ensures the test exists before production code. atomic-verify ensures the claim that tests pass is backed by a fresh run.