---
name: analyze-scenarios
description: Phase 0d of the scenario-first cycle. Synthesises run results from a scenarios doc into a review file in d4d-source/1-reviews/ in the shape parse-review expects, then stops at the Phase 0d user-gate before handoff to /run-cycle.
argument-hint: "<scenario-file-path-or-slug>"
allowed-tools: [Read, Bash, Glob, Grep, Edit, Write]
---

You are translating the run results of a scenario-cycle into a review file that feeds the standard five-phase cycle. Typically run by the primary session.

---

## Inputs (from $ARGUMENTS)

- `<scenario-file-path-or-slug>` — path to a file under `d4d-source/0-scenarios/` with `status: tests-run`. **Required.**

If status is not `tests-run`, refuse — the scenario cycle must complete Phase 0c (with the user-gate cleared) before analysis.

---

## Step 1 — Read everything

Read:

1. The full scenario file — every block, including run results and the `## Footnotes` section.
2. Each evidence path referenced. Don't open every screenshot; do scan logs for unexpected stderr that the run-results lines may have missed.
3. The MVP specs (`d4d-source/docs/dotworld-mvp-spec-product.md` for the post-2026-05-18 product framing, `dotworld-mvp-spec.md` for backend).
4. `d4d-source/3-tasks/task-list.md` and any `task-micro-NN-*` files that landed during Phase 0c.

---

## Step 2 — Extract macro gaps

For each FAIL/INCOMPLETE criterion that did **not** get a micro-fix (or whose micro-fix stayed RED and was carried forward):

- One-line gap description, user-facing — *"the agent's response cited nonexistent files"* beats *"search-grounding test failed."*
- Which scenario + criterion surfaced it.
- Submodule(s) it touches: `dotworld-app`, `dotworld-claude` (watcher), `workspace`, or `cross-cutting`. Note: `dotworld-obsidian` is frozen post-2026-05-18 — if a gap lives in the plugin, escalate it as a spec/scope question rather than a planned fix.
- Severity: P1=blocks a primary flow, P2=blocks a pillar, P3=polish.
- Suspected category: `blocking-issue`, `spec-implication`, `test-gap`, `ux-issue`, or `doc-drift`.

Also capture **micro-fix lessons** — one bullet per micro-fix taken in Phase 0c: what was fixed, what surprised you, what should be tested differently next cycle.

---

## Step 3 — Write the review file

Write `/workspaces/dotworld-dev/d4d-source/1-reviews/YYYY-MM-DD-<cycle-slug>-scenario-review.md`:

```markdown
---
title: Scenario review — <cycle-slug>
date: YYYY-MM-DD
source-scenarios: d4d-source/0-scenarios/<scenario-file>
phase: 1
---

# Scenario review — <cycle-slug>

## Origin
Generated from a scenario-first cycle. Source scenarios doc:
<source-scenarios>. <count> micro-fixes were applied in-loop during Phase 0c;
the items below are the macro gaps that carried forward.

## Scenarios run
- <one bullet per scenario: name, green/red status, one-line outcome>

## Macro gaps (count: N)

### dotworld-app (N items)
1. **P<N>** — <one-paragraph description tying back to scenario + criterion + spec section>
   - Suspected category: <blocking-issue | spec-implication | test-gap | ux-issue | doc-drift>

### dotworld-claude — watcher (N items)
1. ...

### Cross-cutting (N items)
1. ...

(Post-2026-05-18: `dotworld-obsidian` is frozen — see `[[project-obsidian-freeze-pivot]]`. Plugin-side gaps surface as spec/scope escalations, not as macro-gap rows.)

## Micro-fix lessons (count: N)
- <one bullet per micro-fix taken: what was fixed, what surprised, what to test differently next cycle>

## Spec implications (count: N)
- <bullets; mark "ESCALATE" if the user must decide before the cycle can plan>

## Recommended cycle scope
Two-sentence recommendation: which macro gaps the next /run-cycle should tackle now, and which should defer to a later cycle.
```

The file must be **parse-review compatible** — a subsequent `/parse-review <this-file>` call must work against it with no special-casing.

---

## Step 4 — Update the scenario file

Edit `d4d-source/0-scenarios/<scenario-file>`:

- Set `status: analyzed`.
- Add `review-output: d4d-source/1-reviews/<filename>` to the frontmatter.

---

## Step 5 — Post the user-gate summary

Return (and print):

```
[phase-0d-ready] Review: d4d-source/1-reviews/<filename>

Source scenarios: d4d-source/0-scenarios/<source>
Macro gaps surfaced: <count>
  - <one bullet per macro gap, with severity and submodule>
Micro-fix lessons: <count>
Spec escalations: <list, or "none">

USER-GATE: approve to hand off to /run-cycle, OR request changes before handoff. STOPPING here.
```

---

## Rules

- **Don't restate run results verbatim.** This is synthesis. Group, prioritise, surface the load-bearing parts.
- **The review file must be parse-review compatible.** `/parse-review` should work against it without modification.
- **Don't drop spec questions.** If the run revealed a spec ambiguity, surface it as an ESCALATION — `/run-cycle` refuses to plan past unresolved spec questions.
- **No new tests, no new fixes here.** Synthesis only. Tests and fixes belong to Phase 0b/0c (past) or to the downstream cycle (future).
- **User-gate is real.** Once you post `[phase-0d-ready]`, STOP.

---

## Begin

Parse $ARGUMENTS, read, synthesise, write, gate.

$ARGUMENTS