lisa-tdd-implementation

name	lisa-tdd-implementation
description	Test-Driven Development implementation workflow. RED: write failing test, GREEN: minimum code to pass, REFACTOR: clean up. Includes task metadata requirements, verification, and atomic commit practices.

TDD Implementation

Implement code changes using the Test-Driven Development (RED/GREEN/REFACTOR) cycle. This skill defines the complete workflow from task metadata validation through atomic commit.

Task Metadata

Each task you work on must have the following in its metadata:

{
  "plan": "<plan-name>",
  "type": "spike|bug|task|epic|story",
  "acceptance_criteria": ["..."],
  "relevant_documentation": "",
  "testing_requirements": ["..."],
  "skills": ["..."],
  "learnings": ["..."],
  "verification": {
    "type": "ui-recording|api-test|cli-test|database-check|manual-check|documentation",
    "command": "the proof command — must run the actual system (NOT test/typecheck/lint, those are quality gates)",
    "expected": "what success looks like — observable system behavior"
  }
}

All fields are mandatory — empty arrays are ok. If any are missing, ask the agent team to fill them in and wait to get a response.

Workflow

1. Verify task metadata — All fields are mandatory. If any are missing, ask the agent team to fill them in and wait to get a response.
2. Load skills — Load the skills in the skills property of the task metadata.
3. Read before writing — Read existing code before modifying it. Understand acceptance criteria, verification, and relevant research.
4. Follow existing patterns — Match the style, naming, and structure of surrounding code.
5. One task at a time — Complete the current task before moving on.
6. RED — Write a failing test that captures the expected behavior from the task description. Focus on testing behavior, not implementation details.
7. GREEN — Write the minimum production code to make the test pass.
8. REFACTOR — Clean up while keeping tests green.
9. Verify empirically — Run the task's proof command and confirm expected output.
10. Update documentation — Add/Remove/Modify all relevant JSDoc preambles, explaining "why", not "what".
11. Update the learnings — Add what you learned during implementation to the learnings array in the task's metadata.learnings. These should be things that are relevant for other implementers to know.
12. Commit atomically — Once verified, run the /git-commit skill.

TDD Cycle

Always write failing tests before implementation code. This is mandatory, not optional.

TDD Cycle:
1. RED: Write a failing test that defines expected behavior
2. GREEN: Write the minimum code to make the test pass
3. REFACTOR: Clean up while keeping tests green

RED Phase

• Write a test that captures the expected behavior from the task description
• Focus on testing behavior, not implementation details
• The test must fail before you write any production code
• If the imported module doesn't exist, Jest reports 0 tests found (not N failed) — this is expected RED behavior
• For a Fix task, or a Build task that changes user-visible behavior, include a regression test at the highest practical observation level for the reported surface. If the project has a browser, device, or end-to-end harness for that platform (for example Playwright, Maestro, Detox, Cypress, or an equivalent runtime), the RED test plan must include a deterministic spec against the reported surface, using mocked or seeded data where needed.
• The team lead may not waive, defer, or mark that user-visible regression spec as optional, "if cheap", or equivalent. The only exits are a recorded absence of an end-to-end harness for the affected platform, or a genuine technical blocker with a linked build-ready follow-up ticket created before merge and referenced from the PR and source work item.
• For frontend work, the bdd-e2e-coverage rule governs what that spec is sealing: before writing it, add or update the Gherkin scenario with its stable ID in the project's behavior contract, then write aligned automation in the project's configured runner for each platform the scenario requires. The scenario is the specification the RED test encodes — write the scenario first, in the same PR.
• A regression spec is not complete merely because it exists. Completion evidence must prove the spec actually ran and passed in PR CI with a named log line, reporter output, or equivalent execution record. Guard against test.skip, suite-level environment gates, shard filters, and "0 tests" passes.

GREEN Phase

• Write the minimum production code to make the test pass
• Do not optimize, do not add features beyond what the test requires
• For any UI surface the implementation adds or changes, the design-source-of-truth rule requires its design-source declaration to land in the same commit as the surface it describes — DESIGN-SOURCE: <figma-url> when the surface is backed by a Figma node (sync it back first if Figma access exists), or the exception marker DESIGN-SOURCE: none — not in Figma when it genuinely is not captured at the source. scripts/design-source-gate.mjs fails closed on an undeclared surface. Cite the rule; do not restate its marker grammar here.
• Separately, the design-value-binding rule governs where each value on that surface came from: in an axis with a published variable collection, bind the variable and use a screenshot only to verify; in an axis with none, measure and record what you derived. A literal in a typed axis is a block, not a TODO. Cite the rule; do not restate its conditions here.
• The goal is the simplest code that makes the test green

REFACTOR Phase

• Clean up code while keeping all tests green
• Remove duplication, improve naming, simplify structure
• Run tests after every refactor step to confirm nothing breaks

When Stuck

• Re-read the task description and acceptance criteria
• Check relevant research for reusable code references
• Search the codebase for similar implementations
• Ask the team lead if the task is ambiguous — do not guess