mpiton/agentic-atdd/red-cycle

/red <issue-number>

Phase 4a of the diagram. Generates ONE failing acceptance test that mirrors the Gherkin scenario stored in the GitHub sub-issue. Runs the fidelity reviewer in a bounded loop.

When to use

• The orchestrator iterates scenarios from issues.json.
• The user types /red 130 to run a single scenario.

Inputs

• <issue-number> — a GitHub scenario sub-issue created by to-issues-atdd.

Workflow

1. Fetch context

gh issue view <issue-number> --json number,title,body,labels

From the labels:

• level/<use-case|e2e|ui> — selects the test driver.
• rule/<R-NN> — links back to the business rule.
• us/<us-slug> — locates specs/<us-slug>/.

2. Branch

Cut atdd/<us-slug>/scenario-<issue-number> from the integration tip, not from wherever HEAD is. In the main checkout HEAD is the previous scenario's branch; in a fresh worktree it is origin/HEAD. Neither carries the scenarios merged so far.

git fetch origin <integration_branch>
git checkout -b atdd/<us-slug>/scenario-<issue-number> origin/<integration_branch>

integration_branch comes from specs/<us-slug>/issues.json (fallback: .atdd-pipeline.json:integration_branch_pattern). If the branch already exists (resumed run), check it out instead. If it already carries a red(<R-NN>) commit, RED is done: hand off to green-cycle.

3. Generate the test (attempt 1)

Write ONE test file at the conventional path for the project. Honor the level label:

• @use-case — pure domain test, no real I/O, no framework adapters; uses ports / interfaces.
• @e2e — exercises the system through its real adapters; database, HTTP, queues are real (test instances).
• @ui — UI driver against a rendered view.

The test MUST:

• Re-use the exact Given / When / Then wording from the scenario body as comments above the assertions.
• Use the same concrete data values as the scenario (no placeholders, no faker for the values the scenario fixed).
• Make no assertion that the scenario does not state.
• NOT mock the system under test.

Run the test suite. Confirm the new test fails for the expected reason (assertion / missing implementation), not for an unrelated reason (compile error, missing import, wrong setup). If it fails for the wrong reason, fix the setup and retry — that fix does NOT consume a fidelity auto-correction attempt.

This setup loop is bounded: at most 3 setup-fix attempts. If after 3 the test still fails for the wrong reason, STOP and escalate (post a comment on the issue with the wrong-reason failure output and the phrase ESCALATED: red-cycle could not get the test to fail for the right reason.). Do not proceed to the fidelity review on a test that never failed correctly. The cap exists so a broken harness or environment (missing tooling, gitignored env file absent in a worktree) surfaces to a human instead of looping forever — consistent with principle #3 (bounded auto-correction).

4. Fidelity review

Invoke `review-fidelity`. Pass:

• The Gherkin scenario body.
• The test file content.

Receive a verdict OK or REGENERATE with reasons.

5. Auto-correction loop (max 2)

While the verdict is REGENERATE AND the attempt counter is < 2:

1. Increment the attempt counter.
2. Rewrite the test addressing every flagged reason. Do not touch production code in this phase.
3. Re-run review-fidelity.

6. Escalate or hand off

• If VERDICT: OK after at most 2 attempts: commit the test on the branch with message red(<R-NN>): failing test for <scenario title> and hand off to green-cycle. Stage only the files this cycle wrote (the test and its setup), never git add -A.
• If VERDICT: REGENERATE after 2 attempts: post a comment on the issue containing:
• The final reviewer report.
• The diffs of the 2 attempts.
• The phrase ESCALATED: red-cycle exhausted auto-correction.

Leave the branch in place for human inspection. Return without invoking green-cycle.

On any escalation in this skill (here or the step 3 setup cap), commit the leftover work on the branch as wip: escalated at red, no push. Stage only the files this cycle wrote. specs/<us-slug>/ belongs to the orchestrator: never stage it. The tree is clean when no tracked file is modified; the untracked specs/ files stay where they are.

Outputs

• A new test file on the atdd/<us-slug>/scenario-<issue-number> branch.
• specs/<us-slug>/.cycles/<issue-number>/red-fidelity.md — the final reviewer report.

Anti-patterns

• Do NOT modify production code in this phase. RED only.
• Do NOT silence the failure (skip / xfail / commented assertion). The test must run and fail loudly.
• Do NOT mock collaborators that the scenario expects to exercise.

Composition with mattpocock skills

• tdd (mattpocock) covers the red/green/refactor philosophy and the anti-pattern of horizontal slicing. This skill is the ATDD-specific, vertical-slice instance: one scenario → one RED → one GREEN. Use tdd notes for testing taste; this skill for the pipeline mechanics.
• diagnose (mattpocock) is the right escalation tool when a test fails for the wrong reason and the cause is unclear.