Load this skill when continuing Step 3 (TDD Loop) for an in-progress feature. Architecture stubs must already exist (created by the system-architect at Step 2).

Software-Engineer Quality Gate Priority Order

During implementation, correctness priorities are (in order):

Design correctness — YAGNI > KISS > DRY > SOLID > Object Calisthenics > appropriate design patterns > complex code > complicated code > failing code > no code
One @id green — the specific test under work passes, plus test-fast still passes
Commit — when a meaningful increment is green
Quality tooling — lint, static-check, full test with coverage run at end-of-feature handoff

Design correctness is far more important than lint/pyright/coverage compliance. Never run lint (ruff check, ruff format), static-check (pyright), or coverage during the TDD loop — those are handoff-only checks.

Step 3 — TDD Loop

Prerequisites

Exactly one .feature in_progress. If not present, load skill select-feature
On feat/<stem> or fix/<stem> branch (git branch --show-current). If on main, load skill version-control and create/switch to the branch first
Architecture stubs present in <package>/ (committed by Step 2)
Read docs/system.md — understand current system structure and constraints
Read in-progress .feature file — understand acceptance criteria
Test stub files exist in tests/features/<feature_slug>/<rule_slug>_test.py — generated by pytest-beehave at Step 2 end; if missing, re-run uv run task test-fast and commit the generated files before entering RED

Build Test List

List all @id tags from in-progress .feature file
Order: fewest dependencies first; most impactful within that set
Each @id = one TODO item, status: pending
Confirm each @id has a corresponding skipped stub in tests/features/<feature_slug>/ — if any are missing, add them before proceeding

Outer Loop — One @id at a time

WIP limit: exactly one in_progress at all times.

For each pending @id:

INNER LOOP
├── RED
│   ├── Confirm stub for this @id exists in tests/features/<feature_slug>/<rule_slug>_test.py with @pytest.mark.skip
│   ├── Read existing stubs in `<package>/` — base the test on the current data model and signatures
│   ├── Write test body (Given/When/Then → Arrange/Act/Assert); remove @pytest.mark.skip
│   ├── Update <package> stub signatures as needed — edit the `.py` file directly
│   ├── uv run task test-fast
│   └── EXIT: this @id FAILS
│       (if it passes: test is wrong — fix it first)
│
├── GREEN
│   ├── Write minimum code — YAGNI + KISS only
│   │   (no DRY, SOLID, OC, Docstring, type hint here — those belong in REFACTOR)
│   ├── uv run task test-fast
│   └── EXIT: this @id passes AND all prior tests pass
│       (fix implementation only; do not advance to next @id)
│
└── REFACTOR
    ├── Load `skill refactor` — follow its Step-by-Step for this phase
    ├── uv run task test-fast after each individual change
    └── EXIT: test-fast passes; no smells remain

Commit when a meaningful increment is green
Commit when a meaningful increment is green

Quality Gate (all @id green)

uv run task lint
uv run task static-check
uv run task test-coverage           # coverage must pass
timeout 10s uv run task run

If coverage is below the threshold: add test in tests/unit/ for uncovered branch (do NOT add @id tests for coverage).

All must pass before Self-Declaration.

Self-Declaration (once, after all quality gates pass)

Communicate verbally to the system-architect. Answer honestly for each principle:

As a software-engineer I declare that:

1. YAGNI: no code without a failing test — AGREE/DISAGREE | file:line
1. YAGNI: no speculative abstractions — AGREE/DISAGREE | file:line
1. KISS: simplest solution that passes — AGREE/DISAGREE | file:line
1. KISS: no premature optimization — AGREE/DISAGREE | file:line
1. DRY: no duplication — AGREE/DISAGREE | file:line
1. DRY: no redundant comments — AGREE/DISAGREE | file:line
1. SOLID-S: one reason to change per class — AGREE/DISAGREE | file:line
1. SOLID-O: open for extension, closed for modification — AGREE/DISAGREE | file:line
1. SOLID-L: subtypes substitutable — AGREE/DISAGREE | file:line
1. SOLID-I: no forced unused deps — AGREE/DISAGREE | file:line
1. SOLID-D: depend on abstractions, not concretions — AGREE/DISAGREE | file:line
1. OC-1: one level of indentation per method — AGREE/DISAGREE | deepest: file:line
1. OC-2: no else after return — AGREE/DISAGREE | file:line
1. OC-3: primitive types wrapped — AGREE/DISAGREE | file:line
1. OC-4: first-class collections — AGREE/DISAGREE | file:line
1. OC-5: one dot per line — AGREE/DISAGREE | file:line
1. OC-6: no abbreviations — AGREE/DISAGREE | file:line
1. OC-7: ≤20 lines per function, ≤50 per class — AGREE/DISAGREE | longest: file:line
1. OC-8: ≤2 instance variables per class (behavioural classes only; dataclasses, Pydantic models, value objects, and TypedDicts are exempt) — AGREE/DISAGREE | file:line
1. OC-9: no getters/setters — AGREE/DISAGREE | file:line
1. Patterns: no good reason remains to refactor using OOP or Design Patterns — AGREE/DISAGREE | file:line
1. Patterns: no creational smell — AGREE/DISAGREE | file:line
1. Patterns: no structural smell — AGREE/DISAGREE | file:line
1. Patterns: no behavioral smell — AGREE/DISAGREE | file:line
1. Semantic: tests operate at same abstraction as AC — AGREE/DISAGREE | file:line

A DISAGREE answer is not automatic rejection — state the reason and fix before handing off.

Branch Hygiene (before handoff)

Before signalling completion:

git status — working tree must be clean. Commit any remaining changes.
git branch --show-current — must be feat/<stem> or fix/<stem>, never main.
git log main..HEAD --oneline — must show 1+ commits. If empty, nothing was committed on this branch.
git push origin $(git branch --show-current) — all commits must be on origin.

Hand off to Step 4 (Verify)

Signal completion to the system-architect. Provide:

Feature file path
Self-Declaration (communicated verbally, as above)
Summary of what was implemented

Test Writing Conventions

Test File Layout

tests/features/<feature_slug>/<rule_slug>_test.py

<feature_slug> = the .feature file stem with hyphens replaced by underscores, lowercase
<rule_slug> = the Rule: title slugified (lowercase, underscores)

Function Naming

def test_<feature_slug>_<@id>() -> None:

feature_slug = the .feature file stem with spaces/hyphens replaced by underscores, lowercase
@id = the @id from the Example: block

Docstring Format (mandatory)

New tests start as skipped stubs. Remove @pytest.mark.skip when implementing in the RED phase.

@pytest.mark.skip(reason="not yet implemented")
def test_<feature_slug>_<@id>() -> None:
    """
    <@id steps raw text including new lines>
    """

Rules:

Docstring contains Gherkin steps as raw text on separate indented lines
No extra metadata in docstring — traceability comes from function name @id suffix

Markers

@pytest.mark.slow — takes > 50ms (Hypothesis, DB, network, terminal I/O)
@pytest.mark.deprecated — auto-skipped by pytest-beehave; used for replaced Examples

@pytest.mark.deprecated
def test_wall_bounce_a3f2b1c4() -> None:
    ...

@pytest.mark.slow
def test_checkout_flow_b2c3d4e5() -> None:
    ...

Hypothesis Tests

When using @given in tests/unit/:

@pytest.mark.slow
@given(x=st.floats(min_value=-100, max_value=100, allow_nan=False))
@example(x=0.0)
def test_wall_bounce_c4d5e6f7(x: float) -> None:
    """
    Given: Any floating point input value
    When: compute_distance is called
    Then: The result is >= 0
    """
    assume(x != 0.0)
    result = compute_distance(x)
    assert result >= 0

Rules:

@pytest.mark.slow is mandatory on every @given-decorated test
@example(...) is optional but encouraged
Do not use Hypothesis for: I/O, side effects, network calls, database writes

Semantic Alignment Rule

The test's Given/When/Then must operate at the same abstraction level as the AC's Steps.

AC says	Test must do
"When the user presses W"	Send `"W"` through the actual input mechanism
"When `update_player` receives 'W'"	Call `update_player("W")` directly

If testing through the real entry point is infeasible, escalate to PO to adjust the AC boundary.

Quality Rules

Write every test as if you cannot see the production code — test what a caller observes
No isinstance(), type(), or internal attribute (_x) checks in assertions
One assertion concept per test (multiple assert ok if they verify the same thing)
No pytest.mark.xfail without written justification
pytest.mark.skip(reason="not yet implemented") is only valid on stubs — remove it when implementing
Test data embedded directly in the test, not loaded from external files

Test Tool Decision

Situation	Location	Tool
Deterministic scenario from a `.feature` `@id`	`tests/features/`	Plain pytest
Property holding across many input values	`tests/unit/`	Hypothesis `@given`
Specific behavior or single edge case	`tests/unit/`	Plain pytest
Stateful system with sequences of operations	`tests/unit/`	Hypothesis stateful testing

Handling Spec Gaps

If during implementation you discover a behavior not covered by existing acceptance criteria:

Do not extend criteria yourself — escalate to PO
Document the gap in your handoff message to the PO
The PO will decide whether to add a new Example to the .feature file

Extra tests in tests/unit/ are allowed freely (coverage, edge cases, etc.) — these do not need @id traceability.

Signature Design

signatures are written during Step 2 (Architecture) by the system-architect and refined during Step 3 (RED) by the software-engineer. They live directly in the package .py files — never in the .feature file.

Key rules:

Bodies are always ... in the architecture stub
GREEN phase replaces ... with the minimum implementation
REFACTOR phase cleans up the result

Use Python Protocols for external dependencies if they are identified in scope — never depend on a concrete class directly:

from typing import Protocol
from dataclasses import dataclass


@dataclass(frozen=True, slots=True)
class EmailAddress:
    value: str

    def validate(self) -> None: ...


class UserRepository(Protocol):
    def save(self, user: "User") -> None: ...
    def find_by_email(self, email: EmailAddress) -> "User | None": ...

Base directory for this skill: .opencode/skills/implement/ Relative paths in this skill (e.g., scripts/, reference/) are relative to this base directory. Note: file list is sampled.