execute-spec

Execute TDD from SPEC

Test-driven development guided by the approved SPEC SDD. The SPEC is the single source of truth. Every test is derived from a numbered requirement or acceptance criterion.

Internal reasoning and commands are in English. All questions and explanations to the user are in Portuguese (pt-BR).

When to Use

• A .specs/SPEC-{YYYYMMDD}-{feature}.md exists with Status: Approved.
• The user asks to implement a feature, change, or bugfix.
• The user asks to execute or run a SPEC (e.g., "execute the spec", "run the spec", "run TDD from the spec").
• O usuário pede para executar ou rodar um SPEC (ex.: "executar o spec", "rodar o spec", "fazer TDD a partir do spec").
• Before writing implementation code.

When NOT to Use

• Do not use when the SPEC is missing or still in Draft.
• Do not use when the user only wants a code review or fix without tests.
• Do not use when the SPEC explicitly declines a requirement (marked [A DEFINIR]).

Core Principles

1. The SPEC is the oracle. Every test must map to a requirement or acceptance criterion.
2. One vertical slice at a time. One failing test, one passing test, one refactor.
3. No speculative code. Write only the minimum code to make the current test pass.
4. No refactor in RED. Refactor only when the suite is green.
5. Re-validate after every change. Run the full suite before moving to the next slice.

Process

1. Read the SPEC

Load .specs/SPEC-{YYYYMMDD}-{feature}.md and identify:

• Section 4 — numbered requirements (RF-001, RF-002, ...).
• Section 6 — acceptance criteria in BDD Given...when...then.
• Section 7 — task plan and validation strategy.
• Section 3 — files to create or modify.

If the SPEC is not approved, stop and invoke /write-specs.

2. Slice the work

Order the work by the task plan (Section 7). Each slice is one requirement or one acceptance criterion. Never write all tests upfront.

3. Red-Green-Refactor loop

For each slice:

RED    → Write one test that exercises a public seam and fails.
GREEN  → Write the minimum code that passes the test.
REFACTOR → Clean duplication, improve names, respect SOLID while green.

4. Test at the public seam

Test behavior through public interfaces (API, function, component), not internal implementation. Tests must survive internal refactors. See references/tests.md for examples and references/mocking.md for mock rules.

5. Mapping to the SPEC

For each test, include a comment or description pointing to the source requirement:

# Covers RF-003: order total must include tax
# Covers AC-02: Given an empty cart, when checking out, then the system returns 422

6. Re-validate and report

After every slice:

1. Run the full test suite for the affected stack.
2. Run lint / type check.
3. Confirm the SPEC requirement is satisfied.

Report progress to the user in Portuguese and continue automatically to the next slice. Do not ask for approval between slices; the approved SPEC is the source of truth.

Slice concluido: [RF-XXX / AC-YYY]
- Teste: [PASS/FAIL]
- Build: [PASS/FAIL]
- Lint: [PASS/FAIL]

Avançando para o proximo slice: [PROXIMO].

7. Closure

When all slices are green:

• Run the full suite (unit, integration, relevant E2E).
• Run the validation strategy from the SPEC (Section 7.1).
• Update docs/qa/test-plan-.md or equivalent if it exists.
• Invoke /qa-analyst for the mandatory pre-PR review.
• Do not open the PR until QA approves.

Anti-Patterns

• ❌ Writing all tests before any implementation.
• ❌ Testing private methods or internal state.
• ❌ Mismatched expectations in mocks (see references/mocking.md).
• ❌ Refactoring while a test is red.
• ❌ Skipping the validation strategy from the SPEC.

Common Mistakes

References

• write-specs — for producing the SPEC SDD
• qa-analyst — for the mandatory pre-PR review
• diagnose — when a test fails unexpectedly and the cause is unclear
• references/tests.md — test examples and patterns
• references/mocking.md — mocking rules
• references/refactoring.md — refactoring guidance
• references/deep-modules.md — deep module design
• references/interface-design.md — interface design patterns