// Test-Driven Development workflow. Use for ALL code changes - features, bug fixes, refactoring. TDD is non-negotiable.
| name | tdd |
| description | Test-Driven Development workflow. Use for ALL code changes - features, bug fixes, refactoring. TDD is non-negotiable. |
TDD is the fundamental practice. Every line of production code must be written in response to a failing test.
For how to write good tests, load the testing skill. This skill focuses on the TDD workflow/process. For mutation-aware test planning, load the mutation-testing skill and use its resources/mutator-rules.md resource as the source of truth.
mutation-testing skill against the changed coderefactoring skill before deciding what, if anything, to restructureCommit history should show clear RED → GREEN → MUTATE → KILL MUTANTS → REFACTOR progression.
Ideal progression:
commit abc123: test: add failing test for user authentication
commit def456: feat: implement user authentication to pass test
commit ghi789: test: strengthen boundary tests (mutation testing)
commit jkl012: refactor: extract validation logic for clarity
TDD evidence may not be linearly visible in commits in these cases:
1. Multi-Session Work
2. Context Continuation
3. Refactoring Commits
When exception applies, document in PR description:
## TDD Evidence
RED phase: commit c925187 (added failing tests for shopping cart)
GREEN phase: commits 5e0055b, 9a246d0 (implementation + bug fixes)
MUTATE + KILL MUTANTS: commit 7b8c9d0 (strengthened boundary tests)
REFACTOR: commit 11dbd1a (test isolation improvements)
Test Evidence:
✅ 4/4 tests passing (7.7s with 4 workers)
Important: Exception is for EVIDENCE presentation, not TDD practice. TDD process must still be followed - these are cases where commit history doesn't perfectly reflect the process that was actually followed.
Always run coverage yourself before approving PRs.
Before approving any PR claiming "100% coverage":
Check out the branch
git checkout feature-branch
Run coverage verification:
cd packages/core
pnpm test:coverage
# OR
pnpm exec vitest run --coverage
Verify ALL metrics hit 100%:
Check that tests are behavior-driven (not testing implementation details)
For anti-patterns that create fake coverage (coverage theater), see the testing skill.
Look for the "All files" line in coverage summary:
File | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
---------------|---------|----------|---------|---------|-------------------
All files | 100 | 100 | 100 | 100 |
setup.ts | 100 | 100 | 100 | 100 |
context.ts | 100 | 100 | 100 | 100 |
endpoints.ts | 100 | 100 | 100 | 100 |
✅ This is 100% coverage - all four metrics at 100%.
Watch for these signs of incomplete coverage:
❌ PR claims "100% coverage" but you haven't verified
❌ Coverage summary shows <100% on any metric
All files | 97.11 | 93.97 | 81.81 | 97.11 |
❌ "Uncovered Line #s" column shows line numbers
setup.ts | 95.23 | 100 | 60 | 95.23 | 45-48, 52-55
❌ Coverage gaps without explicit exception documentation
"What business behavior am I not testing?"
NOT "What line am I missing?"
Add tests for behavior, and coverage follows naturally.
No exceptions without explicit approval and documentation.
If 100% coverage cannot be achieved:
Step 1: Document in package README
Explain:
Step 2: Get explicit approval
From project maintainer or team lead
Step 3: Document in CLAUDE.md
Under "Test Coverage: 100% Required" section, list the exception
Example Exception:
## Current Exceptions
- **Next.js Adapter**: 86% function coverage
- Documented in `/packages/nextjs-adapter/README.md`
- Missing coverage from SSR functions (tested in E2E layer)
- Approved: 2024-11-15
The burden of proof is on the requester. 100% is the default expectation.
pnpm test:watch)# 1. Write failing test
it('should reject empty user names', () => {
const result = createUser({ id: 'user-123', name: '' });
expect(result.success).toBe(false);
}); # ❌ Test fails (no implementation)
# 2. Implement minimum code
if (user.name === '') {
return { success: false, error: 'Name required' };
} # ✅ Test passes
# 3. Run mutation testing to verify test strength
# 4. Kill surviving mutants (ask human when ambiguous)
# 5. Refactor if needed (extract validation, improve naming)
# 6. Commit
git add .
git commit -m "feat: reject empty user names"
Use conventional commits format:
feat: add user role-based permissions
fix: correct email validation regex
refactor: extract user validation logic
test: add edge cases for permission checks
docs: update architecture documentation
Format:
feat: - New featurefix: - Bug fixrefactor: - Code change that neither fixes bug nor adds featuretest: - Adding or updating testsdocs: - Documentation changesBefore submitting PR:
Example PR Description:
## Summary
Adds support for user role-based permissions with configurable access levels.
## Behavior Changes
- Users can now have multiple roles with fine-grained permissions
- Permission check via `hasPermission(user, resource, action)`
- Default role assigned if not specified
## Test Evidence
✅ 42/42 tests passing
✅ 100% coverage verified (see coverage report)
## TDD Evidence
RED: commit 4a3b2c1 (failing tests for permission system)
GREEN: commit 5d4e3f2 (implementation)
REFACTOR: commit 6e5f4a3 (extract permission resolution logic)
After mutation testing confirms test strength, classify any issues:
| Priority | Action | Examples |
|---|---|---|
| Critical | Fix now | Mutations, knowledge duplication, >3 levels nesting |
| High | This session | Magic numbers, unclear names, >30 line functions |
| Nice | Later | Minor naming, single-use helpers |
| Skip | Don't change | Already clean code |
For detailed refactoring methodology, load the refactoring skill.
let/beforeEach for test dataFor detailed testing anti-patterns, load the testing skill.
Before marking work complete:
let/beforeEach)Turn broad requirements, large stories, epics, features, initiatives, or backlog items into small end-to-end child stories without turning them into technical component tasks. Use when refining a backlog, decomposing epics, planning an MVP or walking skeleton, looking for vertical slices, reducing story size, applying SPIDR/Hamburger/capability slicing, avoiding scatter-gather/component stories, or deciding the first valuable story before implementation planning.
Adversarially review written stories, plans, acceptance criteria, specs, and design mocks to surface missing states, unhandled edge cases, unstated assumptions, unverifiable criteria, and slices that are still too broad or horizontal — then work interactively with the user, one question at a time, to turn each gap into a new acceptance criterion, plan update, mock-state spec, or recommendation to use story-splitting. Use when an existing artifact needs tightening before planning or coding.
Set up and run mutation testing with Stryker, including full-project and diff-against-main runs, then use surviving mutants to strengthen weak or missing tests.
Planning work as vertical slices in small, known-good increments. Use when starting significant work, turning already-split stories into PR-sized implementation plans, planning PRs, or sequencing complex tasks. If the input is a broad story, epic, feature idea, or backlog item that still needs product slicing, use story-splitting first.
Produce a mock-audit storyboard — a single HTML page embedding every UX surface in a scope of work side-by-side, with per-mock audit checklists, a flow diagram, and gap cards for missing mocks. Use before any feature touching multiple UX surfaces begins implementation. Also use when the user says "make it easy for me to see all these mocks in one place", "audit the mocks", or "I want to review the whole flow".
Create an application-specific production parity skill by inspecting an app's docs, source, tests, CI, deployment, infrastructure, config, auth, and environment setup, then asking targeted harness questions only for source-unanswerable decisions. Use when local, CI, PR, preview, staging, or other non-production environments may drift from production behavior; when production-only auth, config, identity-provider groups, feature flags, infrastructure, backing services, or policy differences caused bugs; or when a team wants a reusable skill that detects, documents, tests, and helps fix parity drift for one specific application.