execute-specs · diff

v1.3.1 to v1.4.0

37 added, 1 removed. Audit A to A.

---

name: execute-specs

license: MIT

description: "Use when the user asks to implement an approved SPEC SDD using test-driven development."

metadata:

- version: "1.3.1"

+ version: "1.4.0"

visibility: public

author: afonsoft

url: https://github.com/afonsoft/skills

---

# 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.

+ - Section 0 — the `Ticket` field: resolve the linked GitHub Issue number (e.g. `#123`) if present.

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.

+ When the first slice starts, set the SPEC `Status` to `In implementation` and sync the linked Issue to `in_progress` (see GitHub Issue Status Sync).

### 3. Red-Green-Refactor loop

For each slice:

```text

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](references/tests.md) for examples and [references/mocking.md](references/mocking.md) for mock rules.

### 5. Mapping to the SPEC

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

```python

# 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.

```text

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-<feature>.md` or equivalent if it exists.

+ - Sync the linked Issue to `in_review` (see GitHub Issue Status Sync).

- Invoke `/qa-analyst` for the mandatory pre-PR review.

- Do not open the PR until QA approves.

+ - When the PR opens, sync the Issue to `in_pullrequest`. When the PR merges and delivery is finalized, sync to `done`, set the SPEC `Status` to `Done`, and close the Issue if GitHub did not close it automatically.

+ ## GitHub Issue Status Sync

+ When the SPEC's `Ticket` field points to a GitHub Issue, keep its status label in sync with execution, per the Label Contract in `create-issues`. Status labels are exclusive — always remove the previous one when applying the next. If `gh` is unavailable or the SPEC has no linked Issue, skip the sync and continue — never let label management block TDD.

+ | Moment | Action |

+ | --- | --- |

+ | Implementation starts (first slice) | Swap current status label → `in_progress`; set SPEC `Status: In implementation` |

+ | All slices green (before the QA gate) | Swap → `in_review` |

+ | PR opened | Swap → `in_pullrequest` |

+ | PR merged and delivery finalized | Swap → `done`; set SPEC `Status: Done`; close the Issue if still open |

+ | SPEC canceled at any point | Swap → `canceled` + pt-BR comment with the reason; set SPEC `Status: Canceled` |

+ **Blockers** — PR merge conflict, failing CI that cannot be resolved in the slice, missing dependency, unanswered question, or any other impediment: keep the current status label, add `blocked`, and post a pt-BR comment describing the blocker. When the blocker clears, remove `blocked` and comment the resolution.

+ ```bash

+ # status transition (exclusive)

+ gh issue edit 123 --remove-label todo --add-label in_progress

+ # flag a blocker

+ gh issue edit 123 --add-label blocked

+ gh issue comment 123 --body "Bloqueio: conflito de merge no PR #45 em src/foo.ts. Aguardando resolução."

+ # blocker cleared

+ gh issue edit 123 --remove-label blocked

+ gh issue comment 123 --body "Bloqueio resolvido: conflito do PR #45 resolvido no merge com develop."

+ ```

+ After flagging a blocker, report it to the user in Portuguese and pause that work item — do not mark the slice as done while `blocked`.

## Anti-Patterns

- ❌ Writing all tests before any implementation.

- ❌ Testing private methods or internal state.

- ❌ Mismatched expectations in mocks (see [references/mocking.md](references/mocking.md)).

- ❌ Refactoring while a test is red.

- ❌ Skipping the validation strategy from the SPEC.

## Common Mistakes

| Mistake | Fix |

| --- | --- |

| Implementing before the test | Write the failing test first. |

| The test does not map to the SPEC | Link every test to `RF-###` or `AC-###`. |

| Slice too large | Break the slice until one behavior is tested. |

| Not running the full suite after a green test | Re-validate before moving on. |

+ | Leaving the Issue status label stale | Sync the label at every transition (`in_progress` → `in_review` → `in_pullrequest` → `done`). |

+ | Hiding a blocker | Add `blocked` + a pt-BR comment on the Issue and report to the user; never silently stall. |

## 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