Implementation tdd

Implementation TDD (Artifact-Driven TDD Discipline)

Mental model: This skill is the disciplined worker. It turns spec contracts into failing tests, then writes the minimal code to pass them. Nothing more. No premature optimization, no unrequested abstractions, no scope creep.

The primary focus of this skill is Artifact Compliance and Functional Correctness via Red → Green. Code quality, refactoring, and edge-case hardening are evaluated downstream by code-review (in Refactor Mode if needed).

---

CHEAT SHEET — read this first, every invocation

Operating principles (in priority order)

1. Spec Anchor         (every test must trace back to a spec section)
2. Red First           (test before code, always — except in Refactor Mode)
3. Minimal Green       (least code that passes the tests, no more)
4. One Phase Per Commit (test, feat, refactor — separate commits, signed)
5. Clean Hand-Off      (branch clean, ready for audit before leaving)

Hard rules — NEVER violate

• NEVER write implementation code before tests are Red and committed. The Red commit is the proof that the test is genuine, not post-hoc justification.
• NEVER add features, helpers, or abstractions not required by the failing tests. "I'll need this later" is not a justification. The next sub-task or iteration will justify it.
• NEVER optimize prematurely. No caching "just in case", no async "for future scale", no config "for flexibility". The test demands it → write it. The test doesn't → don't.
• NEVER commit code that doesn't make a previously-failing test pass. If you wrote code and no test demanded it, delete it before commit.
• NEVER merge, push, or close the sub-task from this skill. Those are not in scope. This skill produces code; other skills decide what to do with it.
• NEVER refactor while writing Green code. Green is "make the test pass with minimal change". Refactor is a separate phase (Refactor Mode, after code-review findings).
• NEVER pollute tests with implementation details. Tests test behavior, not implementation. Changing the implementation should not break tests.
• NEVER skip the Red commit. Even for "trivial" changes. The Red commit is the audit trail that proves the test was genuine.
• NEVER write a test that doesn't trace to a spec section. If you can't point to the spec, the test doesn't belong.
• NEVER leave the branch dirty. All work committed before handing off. git status clean.

Current state check (run before starting)

[ ] Current mode: ___ (New Feature / Bug Fix / Refactor Mode)
[ ] Sub-task ID from progress-map: ___
[ ] Target spec section: ___
[ ] Branch: `feat/<slug>` or `fix/<slug>` or `refactor/<scope>`
[ ] Branch clean? `git status` shows nothing uncommitted
[ ] Test runner detected: ___ (vitest / jest / pytest / go test / etc.)
[ ] Test runner works? Try a single test before going Red
[ ] Spec sections to cover: ___ (count + list)
[ ] No uncommitted work from previous iteration

The 3 modes

Mode	When to use	Step sequence	Skip Red?
New Feature	Sub-task says "implement X"	Step 1 → Red → Green → Verify	No
Bug Fix	Sub-task says "fix bug" or code-review found a real defect	Step 1 → Red → Green → Verify	No
Refactor Mode	Routed back from code-review with quality/findings, NO new functionality	Step 1 → Refactor → Verify	YES (existing tests must stay Green)

Commit signatures (the contract)

Phase	Signature	Example
Red	test(scope): <description> (Red)	test(auth): add failing test for password reset (Red)
Green	feat(scope): <description> (Green)	feat(auth): implement password reset endpoint (Green)
Refactor	refactor(scope): <description>	refactor(auth): extract token validator per code-review
Bug fix Green	fix(scope): <description> (Green)	fix(upload): resolve race condition in concurrent uploads (Green)
Issue linkage	Append Closes #N or Refs #N to Green or Refactor commit	feat(auth): ... (Green) - Closes #123

The discipline (one-line summary)

Write the smallest test that fails because the code doesn't exist. Run it Red. Commit. Write the smallest code that makes it Green. Commit. Stop.

---

1. The 3 Modes (decision tree)

The mode determines which steps to run. Choosing the wrong mode is a common mistake that derails the loop.

New Feature

Trigger: Sub-task is "implement X", "add X", "build X", or similar.

Flow: Red → Green → Verify

• Tests are written for behavior not yet implemented
• The Red commit is the proof that the test is genuine
• Green is the minimal code to pass the test
• Hand off to alignment-audit

Pitfall: Writing the implementation first, then the test. This is "test-after", not TDD. The audit will catch it.

Bug Fix

Trigger: Sub-task says "fix X", code-review flagged a real defect (not just quality), or user reports a bug.

Flow: Red → Green → Verify

• First: write a test that REPRODUCES the bug (the test fails on current code)
• The Red commit is the proof that the bug is reproducible
• Green is the minimal fix to make the test pass
• Hand off to alignment-audit

Pitfall: Fixing the bug without a test. Without a regression test, the bug will return. The audit will catch it.

Special case: If the bug is in production code that has no tests yet, the "Red" phase first writes a test for the surrounding behavior, then a specific test that fails because of the bug. The first test is "infrastructure"; the second is the actual repro.

Refactor Mode (only from code-review findings)

Trigger: code-review reports quality findings (naming, modularity, edge cases) — NOT new functionality.

Flow: Verify Green → Refactor → Verify Green

• No Red phase. Refactor Mode assumes existing tests are Green and the goal is to improve code without changing behavior.
• Run the test suite first. If anything is Red, abort Refactor Mode — this is a bug, not a quality issue.
• Refactor to address the findings: rename, extract, restructure, harden edge cases.
• Run the test suite after every meaningful change. If anything goes Red, revert immediately.
• Add regression tests ONLY if code-review identified unhandled edge cases (e.g., a "What-If" stress test scenario that wasn't covered).
• Hand off to code-review (re-review) or alignment-audit if scope expanded

Pitfall: Adding new features in Refactor Mode. If you find yourself writing a test for behavior that doesn't exist, you're in New Feature mode, not Refactor Mode. Route back to the orchestrator.

---

2. The Discipline (the 4 inviolable rules)

These rules are the difference between TDD and "writing code with tests".

Rule 1: Spec Anchor

Every test must trace to a spec section. The chain is:

Spec section → Test name → Test assertion → Implementation code

If any link in this chain is missing, the test is unjustified. Examples:

✅ brand-product-alignment-spec.md § 2 (3-Second Impression) "should feel calm" → test should evoke calm within 3 seconds of page load → assertion expect(getComputedStyle(hero).animationDuration).toBe('1.2s') → implementation animation: ... 1.2s ease-out;

❌ test('should work correctly') — no spec anchor, no behavioral claim, meaningless

Validation: Before each Red commit, walk the chain. If you can't name the spec section, delete the test.

Rule 2: Red First

The test is written BEFORE the implementation. Run it. See it fail. Commit the failure.

Why this matters:

• The Red commit is the audit trail. It proves the test was written before the code (not as an afterthought).
• A test that never goes Red never proves anything. It might pass for any reason, including the test being wrong.
• alignment-audit checks for the Red commit in git history. Missing Red commit = spec violation.

What "Red" must look like:

• The specific test you wrote fails
• The failure message clearly indicates the missing behavior
• Other tests still pass (or are also Red, if they share the missing code)
• NOT Red because of: syntax error, missing import, broken harness

If the test is Red for the wrong reason, fix the test before committing. The Red commit is a contract.

Rule 3: Minimal Green

The implementation is the smallest change that makes the failing test pass. Nothing more.

What "minimal" excludes:

• Caching "for performance" (not demanded by the test)
• Async "for scale" (not demanded by the test)
• Config "for flexibility" (not demanded by the test)
• Helpers that "we'll need later" (premature abstraction)
• Logging beyond the spec'd behavior
• Edge cases the test didn't ask for
• Error messages beyond what's required for the test to pass

What "minimal" includes:

• The exact code path the test exercises
• The exact return value the test asserts
• The exact side effect the test checks

After Green: re-read the diff. If you wrote code that no test demanded, delete it before commit.

Rule 4: One Phase Per Commit

Each phase is a separate commit. The git history tells the story:

• test(scope): ... (Red) — proves the test was genuine
• feat(scope): ... (Green) - Closes #N — proves the implementation is minimal
• refactor(scope): ... — proves the refactor is behavioral-preserving

Audit expectations:

• alignment-audit will check that the Red commit precedes the Green commit in the branch's history
• The Red and Green commits together form the "atomic sub-task" — neither alone is sufficient

If the test passed on the first run (no Red phase), the test was not TDD. Reject and re-do.

---

3. The 4-Step Workflow

┌─ Step 1: CONTEXT & HARNESS ─ Verify sub-task, branch, test runner, build 5-Layer Context
├─ Step 2: RED                ─ Write failing test, run to Red, commit (skip in Refactor Mode)
├─ Step 3: GREEN              ─ Write minimal code to pass, run to Green, commit
└─ Step 4: VERIFY & HAND-OFF  ─ Re-verify, check spec coverage, ensure clean state

Step 1: CONTEXT & HARNESS

Inputs needed:

• Sub-task ID and target spec section (from progress-map.md)
• Current branch (must be a feature/fix/refactor branch, not main)
• Test runner (vitest, jest, pytest, go test, cargo test, etc.)
• Spec artifacts accessible

Actions:

1. git branch --show-current — confirm on the right branch
2. git status — confirm clean (no uncommitted work)
3. If not on a feature branch → git checkout -b feat/<slug> (or fix/ / refactor/)
4. Identify test runner: read package.json / pyproject.toml / go.mod / Cargo.toml / etc.
5. Run a single existing test to verify the harness works (don't skip this)
6. Read the spec section the sub-task references
7. Construct the 5-Layer Context Chain (see § 6)

Test Harness Fallback (if no runner is detected):

• Suggest and scaffold a standard test framework for the tech stack
• Common defaults: vitest for JS/TS, pytest for Python, go test for Go (built-in), cargo test for Rust (built-in)
• Configure minimal test setup before writing any tests
• Verify the runner works on a trivial test before proceeding

Completion gate:

• On correct feature branch
• Branch clean
• Test runner detected and verified working
• Target spec section identified
• 5-Layer Context Chain constructed

Step 2: RED (failing tests)

Skip this step ONLY in Refactor Mode.

Actions:

1. Read the spec section thoroughly
2. Identify the behavioral requirements (one or more, depending on sub-task)
3. Create or update test files in the project's standard test directory
4. Write test cases that assert each behavioral requirement
5. Run the test suite — confirm the new tests are Red
6. Verify the failure message indicates missing behavior (not syntax error, not harness issue)
7. Git Red Commit:

   git add <test files>
   git commit -m "test(scope): <description> (Red)"
   

Test design rules:

• Test behavior, not implementation. (e.g., test "user can reset password" not "calls sendEmail with these args")
• One assertion per test (or one cohesive behavioral claim)
• Use descriptive names: should_<expected>_<when_condition> or behavior-driven style
• Use the spec language, not implementation jargon
• Mock at the boundary (external services, time, random), not internally

Anti-patterns to avoid:

• Testing implementation details (private methods, internal state)
• Asserting on log output or error messages (brittle)
• Test setup that requires 50 lines of fixture (signal the design is too coupled)
• Skipping tests "because they obviously work"
• Copying test patterns from the codebase without checking they fit

Completion gate:

• New tests written
• Tests are Red with the expected failure
• Failure reason is missing behavior, not setup error
• Red commit made with test(scope): ... (Red) signature

Step 3: GREEN (minimal implementation)

Actions:

1. Read the failing tests
2. Implement the minimum code to make each test pass
3. Re-read the diff after each change — if you wrote code that no test demanded, delete it
4. Run the test suite — confirm all tests are Green
5. If a test is still Red, the implementation is incomplete (or the test is wrong) — fix and re-run
6. Git Green Commit:

   git add <implementation files>
   git commit -m "feat(scope): <description> (Green) - Closes #N"
   

   (or fix(scope): ... (Green) - Closes #N for bug fixes)

Minimal Green rules:

• Don't extract a helper "for reuse" if it's only used once
• Don't add a config option "for flexibility" if the spec doesn't mention it
• Don't add error handling "for robustness" if the test doesn't assert on it
• Don't add logging "for observability" if no test checks for it
• DO write the exact code the test exercises
• DO match the spec language in code (naming, types, return values)
• DO keep the implementation flat (no premature hierarchy)

Pitfalls to avoid:

• Refactoring while writing Green code (move to Refactor Mode)
• Adding unrequested features (scope creep — caught by alignment-audit)
• Optimizing performance (premature — caught by alignment-audit if it changes behavior)
• Writing defensive code for edge cases the test didn't ask for

Completion gate:

• All tests Green
• No unrequested code in the diff
• Green commit made with feat(scope): ... (Green) - Closes #N signature
• No premature refactoring in this commit

Step 3.5: REFACTOR MODE (only from code-review)

Skip Step 2 (Red). Refactor Mode assumes existing tests are Green.

Actions:

1. Read the code-review findings carefully
2. Run the test suite first — if anything is Red, ABORT (this is a bug, route back to orchestrator)
3. For each finding:
   • Rename / extract / restructure as appropriate
   • Run tests after every meaningful change
   • If tests go Red, revert immediately (your refactor changed behavior — stop and reconsider)
4. Add regression tests ONLY for unhandled edge cases the review identified
5. Run the full test suite — all Green
6. Git Refactor Commit:

   git add <files>
   git commit -m "refactor(scope): <description of what was addressed>"
   

Refactor Mode rules:

• DO NOT add new features (route to New Feature mode)
• DO NOT add unrequested abstractions (the refactor's job is to address findings, not to redesign)
• DO preserve all existing test coverage
• DO keep each refactor commit focused (one finding per commit if possible)
• DO verify Green after every change, not just at the end

Anti-patterns to avoid:

• "While I'm in here" additions (addressing findings not in the review)
• Renaming everything in the file (renaming only what the review asked for)
• Adding tests for code that wasn't part of the review
• Skipping the test re-run after a change (catching regressions early is the whole point)

Completion gate:

• All review findings addressed
• Test suite still all Green
• No new behavior added
• Refactor commit made with refactor(scope): ... signature

Step 4: VERIFY & HAND-OFF

Actions:

1. Re-run the full test suite — all Green
2. Cross-check spec coverage — for each requirement in the target spec section, confirm there's a passing test
3. git status — clean (no uncommitted changes)
4. git log main...HEAD — verify the Red and Green commits are in order
5. No debug code, no commented-out code, no TODO comments left behind
6. No unrequested changes in the diff (no drive-by refactors, no formatting changes unrelated to the sub-task)

Verification checklist (run before hand-off):

[ ] All tests pass
[ ] Spec section requirements all have corresponding passing tests
[ ] Red commit precedes Green commit in git log
[ ] git status is clean
[ ] No debug code, commented code, or TODOs left
[ ] No unrequested changes in the diff
[ ] Commit messages follow the signature contract
[ ] Issue linkage in Green commit (if applicable)

Hand-off:

• The sub-task is NOT marked complete by this skill
• Hand off to agentic-dev-loop (which routes to alignment-audit then code-review)
• Do NOT mark [x] in progress-map.md — that's the orchestrator's job after Dual Clean Pass

---

4. The 5-Layer Context Chain (operationalized for TDD)

The canonical 5-Layer Context Chain (defined in agentic-dev-loop) is constructed by the orchestrator, but this skill also reads and updates it during execution.

Read on entry

Layer	Source
1. Product & Brand Understanding	brand-product-alignment-spec.md § 1, § 2, § 4
2. Active Branch & Target Scope	git branch --show-current, progress-map.md Issue reference
3. Phase Objective	progress-map.md active Phase
4. Active Task & Spec Contracts	progress-map.md Sub-Task + target spec section
5. Execution & Harness Constraints	package.json / pyproject.toml / etc., test runner command

Update on exit

The skill does not write the context back — that's the orchestrator's job. But it MUST keep the context in mind throughout execution:

• Layer 4 (Active Task): stay focused on the sub-task; don't drift
• Layer 5 (Harness): if a test fails for harness reasons, fix the harness, not the test

---

5. Commit Conventions (the contract)

Per-phase commits

Phase	Signature	When
Red	test(scope): <what the test asserts> (Red)	After test is Red and verified
Green	feat(scope): <what was implemented> (Green)	After tests are Green and verified
Green (bug fix)	fix(scope): <what was fixed> (Green)	After fix and regression test are Green
Refactor	refactor(scope): <what was refactored>	After refactor preserves all tests Green
Test addition in Refactor	test(scope): <new edge case covered>	After new regression test is added (and Green)

Scope conventions

<scope> should be the module, component, or feature area:

• feat(auth):, feat(payments):, feat(upload):
• test(auth):, test(payments):
• fix(race-condition):, fix(memory-leak):
• refactor(token-validator):, refactor(error-handler):

Avoid generic scopes (feat(code):, feat(stuff):) — they defeat the audit trail.

Issue linkage

• Green commits should include Closes #N if the sub-task maps to a GitHub Issue
• Refactor commits should include Refs #N (do not close, since the implementation is unchanged)
• Red commits typically don't need issue linkage (they're preparation for the Green that closes)
• Spec-only work (not part of this skill) uses Refs #N

Multi-commit sub-tasks

If a sub-task requires more than one Red+Green cycle (because it has multiple distinct behaviors), each cycle gets its own commit pair. The sub-task is complete when all behaviors are covered.

---

6. Test Harness Setup (the fallback)

If the project has no test runner, this skill scaffolds one. This is the only situation where the skill modifies the project structure beyond the sub-task's scope.

Detection

Check for these in order:
  1. package.json: look for "test" script, "vitest", "jest", "mocha", etc.
  2. pyproject.toml / setup.py / setup.cfg: look for "pytest", "unittest"
  3. go.mod: built-in `go test`
  4. Cargo.toml: built-in `cargo test`
  5. .csproj / package.json (C#): look for test projects
  6. Other: scan for *.test.*, *_test.*, *.spec.* files

If none found → scaffold.

Scaffolding defaults

Tech stack	Default	Setup
JS/TS	vitest	npm install -D vitest @vitest/ui; add "test": "vitest" to package.json; create vitest.config.ts
Python	pytest	pip install pytest; create pytest.ini or pyproject.toml [tool.pytest.ini_options]
Go	go test (built-in)	No setup; just write *_test.go files
Rust	cargo test (built-in)	No setup; just write #[cfg(test)] modules
Ruby	rspec	Add to Gemfile; bundle install; create spec/spec_helper.rb

Verify the runner works by writing a trivial test (e.g., expect(1+1).toBe(2)) and running it before proceeding.

Scaffolding commit

If the harness was set up, that's a separate commit:

chore(test): scaffold vitest test runner

Then the Red/Green commits follow as normal.

---

7. Anti-Patterns (what NOT to do)

These are the most common ways TDD gets corrupted. The audit and review will catch them; better to avoid them upfront.

Premature optimization

❌ "This needs caching because it'll be slow at scale" ✅ Only cache if a performance test demands it

❌ "I'll make this async so it scales better" ✅ Only async if the test (or a real concurrent scenario test) requires it

❌ "Let me add a config option for flexibility" ✅ Only config if the spec demands multiple values

Unrequested abstractions

❌ Extracting a helper used in only one place ❌ Adding a base class "for future subclasses" ❌ Creating an interface "for future implementations" ❌ Adding a factory "for flexibility"

Rule: if a helper is used twice AND the abstraction makes the code clearer, extract. Otherwise don't.

Scope creep

❌ "While I'm in here, let me also fix this other thing" ❌ "This test would be more robust with this additional assertion" ❌ "I'll add a logging statement so debugging is easier"

If you find yourself doing this, stop. That's a separate sub-task.

Skipping the Red commit

❌ Writing the implementation, then the test, then committing both together ❌ "The test is trivial, I'll just commit the implementation" ❌ "I'll just verify mentally that the test would have been Red"

The Red commit is the audit trail. Without it, the test could be post-hoc justification.

Test pollution

❌ Tests that depend on other tests' state ❌ Tests that modify global state without cleanup ❌ Tests that depend on test execution order ❌ Tests that share fixtures without isolation ❌ Tests that hit real external services

Each test should be independently runnable, in any order, with no side effects on other tests.

Implementation-coupled tests

❌ expect(component.state.isLoading).toBe(false) (testing internal state) ❌ expect(mockFunction).toHaveBeenCalledWith(args) (testing implementation) ❌ expect(component.find('div.loading')).toHaveLength(1) (testing structure)

✅ expect(getByText('Loading...')).toBeInTheDocument() (testing user-visible behavior) ✅ expect(screen.getByRole('button')).toBeDisabled() (testing accessibility) ✅ await user.click(button); expect(onSubmit).toHaveBeenCalledWith(payload) (testing observable outcome)

---

8. Failure Modes

Symptom	Cause	Recovery
Test is Red for wrong reason (syntax error, missing import)	Harness issue or test setup error	Fix the test/harness, re-run, verify it's Red for the right reason, then commit
Test won't go Red (always Green)	Implementation already exists, or test doesn't actually test missing behavior	Verify the test exercises behavior that doesn't exist; if it does, the spec might be wrong — escalate
Test passes immediately after writing	TDD discipline broken — you wrote the implementation first	Reject the commit, delete the implementation, run the test (should fail), then commit Red first
Green requires huge refactor	The implementation is the wrong shape for the test	This is a design problem, not a TDD problem. Stop. Discuss with the user whether the spec or the test should change.
Green requires touching many unrelated files	The sub-task was too big (or the design is too coupled)	Stop. Route back to orchestrator — sub-task needs to be split in progress-map
Refactor Mode breaks tests	The refactor changed behavior	git revert the refactor commit, start over more carefully
Cannot identify the test runner	Project has no tests and no manifest hints	Use the scaffolding fallback (§ 6)
Test runner is broken or wrong version	Environment issue	Fix the environment, do not skip tests
Sub-task references a spec section that doesn't exist	progress-map out of sync with spec	Stop, route back to orchestrator (cascade)
Branch is dirty when starting (uncommitted work from prior session)	Previous hand-off was incomplete	Commit the existing work first (as appropriate), or git stash it, then proceed
Implementation requires 100+ lines	The sub-task is too big	Stop, route back to progress-mapper to split
Audit fails because of unrequested changes	Scope creep happened	Revert the unrequested changes, re-commit
Two test files need to coordinate (shared state)	Test design issue	Refactor to isolate tests; use beforeEach with fresh state

---

9. Worked Examples

Example A: New Feature — Password Reset

Sub-task from progress-map: 1.1.3 — Add password reset endpoint Target spec: backend-architecture-spec.md § 1 (System Overview) + § 3 (Communication & Reliability) Mode: New Feature

Step 1: Context & Harness
  - Branch: feat/auth-password-reset (already on it)
  - Test runner: pytest (verified by running existing test)
  - Spec: password reset endpoint with email token, 1hr expiry, rate-limited
  - Context chain constructed

Step 2: Red
  - Write test_password_reset.py:
    - test_reset_request_with_valid_email_returns_200
    - test_reset_request_creates_token_in_db
    - test_reset_token_expires_after_1_hour
    - test_reset_with_expired_token_returns_400
    - test_reset_with_invalid_token_returns_400
    - test_reset_request_is_rate_limited
  - Run pytest → 6 tests Red (expected, no implementation yet)
  - Verify failure messages: "AttributeError: module 'auth' has no attribute 'reset_password'"
  - Commit: "test(auth): add failing tests for password reset (Red)"

Step 3: Green
  - Implement reset_password() function — minimal, no abstraction
  - Implement token storage (simple DB insert)
  - Implement rate limit (simple counter)
  - Run pytest → 6 tests Green, no other tests broken
  - Re-read diff: no unrequested code? yes
  - Commit: "feat(auth): implement password reset endpoint (Green) - Closes #123"

Step 4: Verify & Hand-off
  - Re-run pytest → all Green
  - git status → clean
  - git log → Red then Green in order
  - Cross-check spec: 6 requirements, 6 tests, all covered
  - No debug code, no TODOs
  - Hand off to alignment-audit

Example B: Bug Fix — Race Condition

Sub-task from progress-map: 2.3.1 — Fix race condition in concurrent uploads (raised by code-review) Mode: Bug Fix

Step 1: Context & Harness
  - Branch: fix/upload-race-condition
  - Test runner: pytest
  - Spec: backend-architecture-spec.md § 5 (Security & Data Integrity) — concurrent writes must not corrupt state
  - Context chain constructed

Step 2: Red (the repro)
  - Write test_concurrent_uploads.py:
    - test_concurrent_uploads_dont_corrupt_file (the actual repro)
    - test_upload_locks_during_write (precautionary)
  - Run pytest → tests Red (current code has the race)
  - Verify: test fails with "file is corrupted" or similar (not setup error)
  - Commit: "test(upload): add failing tests for concurrent upload race (Red)"

Step 3: Green
  - Implement file lock (minimal — single-process lock first, no distributed locking)
  - Run pytest → tests Green
  - Re-read diff: no distributed locking added? correct, minimal
  - Commit: "fix(upload): add file lock to prevent concurrent corruption (Green) - Closes #456"

Step 4: Verify & Hand-off
  - All Green
  - Cross-check: spec § 5 requirement met
  - Hand off to alignment-audit

Example C: Refactor Mode — Extract Class

Triggered by: code-review finding on previous iteration: "TokenValidator has 3 responsibilities, extract to separate class" Mode: Refactor (no Red)

Step 1: Context & Harness
  - Branch: refactor/auth-token-validator
  - Test runner: pytest
  - Existing tests: 24 tests for auth, all currently Green
  - Verify Green first: pytest → 24 passed

Step 3.5: Refactor
  - Run tests → all Green (baseline)
  - Extract TokenValidator class from auth.py to auth/token_validator.py
  - Update auth.py to use the new class
  - Run tests → 24 Green? yes
  - Rename internal methods for clarity (per code-review finding)
  - Run tests → 24 Green? yes
  - Re-read diff: only the rename + extract? yes, no new features
  - Commit: "refactor(auth): extract TokenValidator per code-review"

Step 4: Verify & Hand-off
  - All Green
  - git status clean
  - No new behavior, no new tests needed
  - Hand off to code-review (re-review)

---

10. Hand-Off Protocol

This skill does NOT close the sub-task. Hand-off is to the orchestrator.

Hand-off to alignment-audit

After Green commit:
  - All tests pass
  - Branch clean
  - Red + Green commits in order
  - Issue linkage in Green commit (if applicable)
  - No unrequested changes in diff
  → Signal to orchestrator: "Implementation complete, ready for alignment-audit"

Hand-off to code-review (after audit Clean Pass)

Handled by orchestrator, not by this skill.
This skill should NOT directly invoke code-review.

Hand-off back to progress-mapper (when sub-task is too big)

If during Step 3 you realize the sub-task is too big:
  - Stop. Do NOT commit incomplete work.
  - Revert any uncommitted changes
  - Signal to orchestrator: "Sub-task X.Y.Z is too large, request split in progress-mapper"

Hand-off back to orchestrator (cascade)

If during execution you discover a spec contradiction:
  - Stop. Do NOT commit anything.
  - Document the contradiction with evidence
  - Signal to orchestrator: "Escalation needed, see <details>"

---

11. Anti-sycophancy reminder (applies to this skill too)

This skill exists to serve the project and the user via the TDD discipline. It does NOT exist to:

• Skip the Red commit because the work "feels obvious"
• Add unrequested features because "the user would probably want it"
• Refactor opportunistically while writing Green
• Make the implementation "nice" at the cost of minimal
• Pretend tests are Red when they're not
• Pass off the sub-task as complete when the spec isn't fully covered

If the sub-task requires more than one TDD cycle, the orchestrator should split it — not this skill silently expanding scope. If the spec is wrong, the cascade handles it — not this skill silently working around it.

TDD discipline is the contract. The Red commit is the proof. The minimal Green is the discipline. Refactor is separate. Spec is the anchor. Test is the assertion. Commit is the trail.

If any of these break, the loop loses its auditability. Hold the line.