# End-to-end walkthroughs

Four cycle-by-cycle traces of the engine commands — backend ticket,
free-form prompt, UI track, and a blocked path. Each walkthrough cites
a checked-in **golden transcript** under [`tests/golden/baseline/`](../tests/golden/baseline/);
the transcripts are regenerated by `python3 -m tests.golden.capture` and
diffed in CI, so the cycle counts and directive names below stay
in sync with the engine's actual behavior.

> Behavior demos (autonomy, commit policy, hard floor, verification)
> live in [`showcase.md`](showcase.md). This file is the cycle-trace
> companion: input → directives → outcome.

---

## 1. Backend ticket → ship — `/implement-ticket`

**Anchor:** [`tests/golden/baseline/GT-1/`](../tests/golden/baseline/GT-1/) ·
[`tickets/gt-1-happy.json`](../tests/golden/sandbox/tickets/gt-1-happy.json)

**Input** — a ticket payload with three concrete acceptance criteria:

```text
GT-1-MULT — Add multiply(a, b) to the toy calculator
AC: signature multiply(a: int, b: int) -> int returning the product;
    edge cases multiply(0, n)=0, multiply(-2, 3)=-6;
    pytest test_multiply_returns_product in tests/test_calculator.py.
```

**Trace** — five cycles, exit code `0` on the last:

| Cycle | Directive | What the agent does |
|---|---|---|
| c1 | `create-plan` | Builds the three-step plan (impl, test, run) |
| c2 | `apply-plan` | Edits `src/calculator.py` and `tests/test_calculator.py` |
| c3 | `run-tests` | `pytest` — `4 passed` (targeted scope) |
| c4 | `review-changes` | Four judges (bug, security, test-coverage, code-quality) — `success` |
| c5 | _(none)_ | Engine emits the delivery report, exits `0` |

**Outcome** — verified delivery report at
[`GT-1/delivery-report.md`](../tests/golden/baseline/GT-1/delivery-report.md):
plan, changes, test verdict, judge findings, suggested next command
(`/commit`).

**Anchored in:** [`commands/implement-ticket.md`](../dist/agent-src/commands/implement-ticket.md)
(eight-step contract) · [`work_engine/dispatcher.py`](../dist/agent-src/templates/scripts/work_engine/dispatcher.py)
(`STEP_ORDER`).

---

## 2. Free-form prompt → ship — `/work`

**Anchor:** [`tests/golden/baseline/GT-P1/`](../tests/golden/baseline/GT-P1/) ·
[`prompts/gt-p1-high.txt`](../tests/golden/sandbox/prompts/gt-p1-high.txt)

**Input** — one line, no AC, no ticket:

```text
Add modulo(a, b) to src/calculator.py — return a % b for ints
```

**Trace** — six cycles. The extra cycle vs. GT-1 is the
`refine-prompt` step that reconstructs the prompt into AC + assumptions
+ confidence band before any plan runs:

| Cycle | Directive | Effect |
|---|---|---|
| c1 | `refine-prompt` | High confidence — AC reconstructed, no halt |
| c2 | `create-plan` | Two-step plan |
| c3 | `apply-plan` | Edits `src/calculator.py` |
| c4 | `run-tests` | targeted pass |
| c5 | `review-changes` | judges green |
| c6 | _(none)_ | delivery report, exit `0` |

**Outcome** — `success`. The same dispatcher and judges as GT-1; only
the input envelope (`input.kind="prompt"` vs `"ticket"`) differs.

**Anchored in:** [`commands/work.md`](../dist/agent-src/commands/work.md) ·
[`skills/refine-prompt/SKILL.md`](../dist/agent-src/skills/refine-prompt/SKILL.md)
· [`docs/contracts/adr-prompt-driven-execution.md`](contracts/adr-prompt-driven-execution.md).

---

## 3. UI improvement → review-loop ship — `/work` (UI track)

**Anchor:** [`tests/golden/baseline/GT-U2/`](../tests/golden/baseline/GT-U2/) ·
[`diffs/gt-u2-improve-diff.diff`](../tests/golden/sandbox/diffs/gt-u2-improve-diff.diff)

**Input** — a Blade diff that adds a `<label>` and a heading change to
`resources/views/contact.blade.php`. The input shape (a diff, not a
prompt) routes the engine onto the **UI track** instead of the
generic implement loop.

**Trace** — six cycles, none of them `create-plan` / `apply-plan` /
`run-tests`. The UI track has its own directive set:

| Cycle | Directive | Effect |
|---|---|---|
| c1 | `existing-ui-audit` | Inventory existing components / tokens before any new design |
| c2 | `ui-design-brief` | Brief for the proposed change |
| c3 | _(none — `_no_directive`)_ | Engine threads forward to the apply step |
| c4 | `ui-apply-plain` | Apply the diff |
| c5 | `ui-design-review-plain` | Design review judge |
| c6 | _(none)_ | delivery report, exit `0` |

**Outcome** — `success`. The audit-first ordering is enforced by the
[`ui-audit-gate`](../dist/agent-src/rules/ui-audit-gate.md) rule: any
non-trivial UI change without `state.ui_audit` halts before design.

**Anchored in:** [`docs/ui-track-mental-model.md`](ui-track-mental-model.md) ·
[`rules/ui-audit-gate.md`](../dist/agent-src/rules/ui-audit-gate.md) ·
[`skills/existing-ui-audit/SKILL.md`](../dist/agent-src/skills/existing-ui-audit/SKILL.md).

---

## 4. Blocked on ambiguity — `/implement-ticket` halts

**Anchor:** [`tests/golden/baseline/GT-2/`](../tests/golden/baseline/GT-2/) ·
[`tickets/gt-2-ambiguity.json`](../tests/golden/sandbox/tickets/gt-2-ambiguity.json)

**Input** — a ticket whose AC list contains a vague entry:

```text
GT-2-DIV — divide(a, b)
AC: ... vague acceptance criteria at position(s) 2 ...
```

**Trace** — one cycle, exit code `1`:

| Cycle | Directive | Effect |
|---|---|---|
| c1 | _(none)_ | Engine refuses to plan; surfaces refine prompt |

**Halt surface** — the engine does not write a plan, does not edit any
file, and emits a numbered-options block (verbatim from
[`GT-2/halt-markers.json`](../tests/golden/baseline/GT-2/halt-markers.json)):

```text
> Ticket GT-2-DIV is missing: vague acceptance criteria at position(s) 2.
> 1. Run `/refine-ticket GT-2-DIV` and re-invoke `/implement-ticket`
> 2. Provide the missing details in chat — I'll merge them into the ticket
> 3. Abandon this ticket — too vague to implement
```

**Outcome** — `halt_unhandled`; the run is recorded as **blocked** in
the outcome-aware telemetry (`outcomes: ["blocked"]`, see
[P2 #9](../agents/roadmaps/road-to-1-15-followups.md#phase-9--outcome-aware-telemetry-p2-9)).
No work is committed, no auto-guess is taken.

**Anchored in:** [`rules/ask-when-uncertain.md`](../dist/agent-src/rules/ask-when-uncertain.md)
· [`rules/non-destructive-by-default.md`](../dist/agent-src/rules/non-destructive-by-default.md)
· [`skills/refine-ticket/SKILL.md`](../dist/agent-src/skills/refine-ticket/SKILL.md).

---

## Reproducing these locally

```bash
python3 -m tests.golden.capture --scenarios GT-1 GT-P1 GT-U2 GT-2
```

Each scenario writes a fresh `transcript.json`, `delivery-report.md`,
and `halt-markers.json` under `tests/golden/baseline/<id>/`. CI diffs
the regenerated output against the committed baseline; drift fails the
build via the `roadmap-progress-check` and `golden-replay` tasks.
