---
name: demo-guide
version: 2.0.0
description: '[Documentation] Use when you need to generate a step-by-step demo guide (demo script / walkthrough) covering all main user stories and their test cases — scope from a named feature, else the current working context, else confirm with the user — explaining for each case how the domain data is stored/changed and how the domain solves the feature. Triggers: demo guide, generate demo guide, demo script, demo walkthrough, how to demo, prepare demo, sprint demo, user story demo.'
---

<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:START -->

> **[BLOCKING]** Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval.
> **[BLOCKING]** Before each step or sub-skill call, update task tracking: set `in_progress` when step starts, set `completed` when step ends.
> **[BLOCKING]** Every completed/skipped step MUST include brief evidence or explicit skip reason.
> **[BLOCKING]** If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.

<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:END -->

## Quick Summary

**Goal:** **UNDERSTAND the feature first, then script it** — investigate the capability end-to-end until you can answer the comprehension bar with `file:line`, and only then produce a stakeholder-ready demo guide that lists every **main user story** with its **REAL test-case IDs**, gives a **step-by-step demo flow** per case, explains **how the domain stores/changes the data and how that solves the feature**, and places every case on the **proof ladder** — so the presenter can show the behaviour, explain the data behind it, and never claim proof that was not earned.

**Summary — read this if nothing else.** A demo guide written from names and guesses stages a demo that breaks in the room. So: investigate first, prove every claim, then write. Main steps, in order:

1. **RESOLVE scope** — prompt → current working context → `AskUserQuestion`. NEVER invent the feature silently.
2. **LOAD the contract** (`references/demo-guide-template.md`) and **SIZE the target into a tier S0–S4**; announce both in one line.
3. **DECOMPOSE into story groups** (≥2 from tier S2) and **BREAK THE WORK INTO TASKS before the first deep read** — `TaskList` first; a group task completes only when its block is **on disk**.
4. **[BLOCKING GATE] UNDERSTAND the feature** — clear the 6-question comprehension bar with `file:line` each, **delegating to read-only investigation skills** (`/scout`, `/investigate`, `/debug-investigate`, `/graph-trace`, `/spec-index`) when a direct read cannot answer one. No demo step is written before this gate clears.
5. **GATHER the five inventories** — stories + REAL IDs · domain storage/solution · demo path & setup · proof · discriminator — each on its own degradation **ladder** ending in a **stated blocker**, never in invention.
6. **MAP story → cases** and persist the map before writing.
7. **TRACE domain storage & solution per case** — read the entity/migration/handler; never infer persistence from names.
8. **OPEN the guide + ledger before case one, ACCUMULATE story by story** on disk; announce anything deferred or dropped.
9. **PROVE & VALIDATE** — place every case on the proof ladder, write the transparency note, run the validation gate.

**Flags:** `feature-or-scope` arg · `--context` · `--output` · `--lang` · `--html` · `--stories`.

**Workflow:**

0. **Resolve Scope, Load Contract, Size & Task** — scope precedence prompt → context → ASK; read the template contract; size into a tier; decompose into story groups; create the task list BEFORE the first deep read.
1. **Understand the Feature FIRST [BLOCKING]** — clear the comprehension bar; delegate gathering to read-only skills; write the Understanding Brief to disk.
2. **Gather the Five Inventories** — portable discovery via `docs/project-config.json`; every inventory walks its ladder and records the rung it landed on.
3. **Map Stories → Cases** — main stories, REAL `TC-*` / test IDs, coverage gaps named.
4. **Trace Domain Storage & Solution** — per case: what is persisted/changed, by which entity/migration/handler, and which rule consumes it (`file:line` each).
5. **Open the Guide + Ledger, Accumulate** — spine first, one block per story group, ledger updated as each lands.
6. **Write Each Case** — setup → numbered demo flow → expected result as the discriminator → domain storage/solution.
7. **Prove** — proof ladder per case + test-execution transparency note.
8. **Validate** — the gate below; nothing declared done before it passes.

**Key Rules (the contract):**

- **UNDERSTAND BEFORE YOU SCRIPT.** The Step 1 comprehension bar is a **[BLOCKING] gate**: until you can answer all six questions with `file:line`, you have no demo to write. — why: a demo step invented from a screen name is a demo that fails live, in front of the people it was written for.
- **Scope precedence is prompt → current context → ASK.** An explicit feature in the prompt wins; else derive from current work; else `AskUserQuestion` — NEVER invent a feature.
- **Every case carries four parts:** setup/preconditions · numbered **step-by-step demo flow** · **expected result phrased as the discriminator** vs the old behaviour · **how the domain stores/changes data & solves the feature**. A case missing the storage/solution part is incomplete.
- **PROOF IS EARNED, NEVER ASSERTED.** Every case sits on one of the four proof rungs (Step 7), and `✅ ran` is licensed **only** by a test executed this session with its command and result recorded. There is no fifth rung: a case you cannot place is a **stated blocker**.
- **REAL IDs ONLY — NEVER invent a test case ID.** A story with no case says _"no test covers this"_ and is recorded as a coverage gap. — why: a fabricated ID retires a risk that is still live.
- **Cite `file:line` for every storage/behaviour claim** — read the entity, the mapping, and the migration. NEVER infer persistence from a field name.
- **A demo step is traced to a real user path, or it is a stated blocker** — NEVER an invented click, endpoint, or screen, and never state faked by a path a user could not reach.
- **DELEGATE THE GATHERING, NEVER THE SCRIPTING.** Read-only delegates only; their output is INPUT, re-verified at `file:line` before it becomes a claim. NEVER delegate to a mutating or findings-emitting skill (`/fix`, `/changes-review`, `/code-review`, `/plan-execute`).
- **ACCUMULATE ON DISK, NEVER IN CONTEXT.** Open the guide before case one; append per case and per story group; synthesize the guide-level sections **from the written blocks**. — why: partial results on disk beat complete results that never got written.
- **NO SECRET VALUES, ANYWHERE.** Setup steps, run commands, and seed instructions name the setting, the file, and the account **role** — never a credential, token, key, connection string, or customer identifier. Secrets render `<redacted:…>` from the moment they would enter context.
- **NO SILENT TRUNCATION.** Anything deferred, sampled, or dropped is named in the guide header AND the chat summary — bounded coverage must never read as complete coverage.
- **Portable — discover, don't hardcode.** Resolve source roots, spec/test locations, run commands, and output dir from `docs/project-config.json`; degrade gracefully and say which rung you landed on.
- **Scale buys MORE STORY GROUPS, never FEWER PARTS per case.** _"Too big to demo properly"_ is a conclusion this skill may never reach.

**Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act.**

---

# Demo Guide — Investigate-First, Proof-Carrying Demo Script

You are an **investigator first, a presenter's coach second** — in that order, and the order is the whole point.

- **As an investigator** you learn the feature before you script it: which capability it delivers, which entity owns the state it changes, how the data flows from the user's click to the persisted row and back to the pixel that proves it, and which rule makes the outcome correct. You read the code; you never infer persistence from a name.
- **As a presenter's coach** you hand a human a script they can run live in front of stakeholders: staged through real user paths, phrased as the discriminator that would have been WRONG under the old behaviour, and backed by an honest statement of what was actually proven versus merely traced.

> **The bar:** a presenter who reads this guide could (a) stage the preconditions without asking anyone, (b) run every case live without improvising a step, (c) answer _"where is that stored and what makes it correct?"_ for any case a stakeholder challenges, and (d) state exactly which cases are backed by a green test and which are being shown by trace alone. Anything less is a wish-list, not a demo guide.

Instructions, not documentation: this skill teaches HOW to build the guide from real project evidence, adapting to whatever the project actually has (specs, tests, PBIs, or just a diff).

## Invocation

```
/demo-guide [feature-or-scope] [--context] [--output path] [--lang xx] [--html] [--stories "A,B"]
```

| Flag / arg         | Meaning                                                                                            |
| ------------------ | -------------------------------------------------------------------------------------------------- |
| `feature-or-scope` | Named feature, spec title, PBI/story id, path, or free-text scope. Highest precedence.             |
| `--context`        | Force "derive scope from current working context" (branch diff / staged + unstaged / active work). |
| `--output path`    | Where to write the guide. Default: project demo-guide dir (see Configuration), else a temp file.   |
| `--lang xx`        | Also emit a translated copy in the given language (keep code identifiers/paths/IDs in English).    |
| `--html`           | After the markdown, offer/produce a self-contained HTML runbook (via the Artifact flow).           |
| `--stories "A,B"`  | Restrict to the named stories instead of all main stories.                                         |

## Step 0 — Resolve Scope, Load the Contract, Size & Task (cheap — costs seconds)

**0.1 Resolve scope (prompt → context → ASK).** Apply the precedence strictly — the skill's defining behaviour:

1. **Prompt names a feature/scope** → use it. Normalise to a concrete target: a spec file, a PBI/story id, a set of changed files, or a keyword set. Confirm it resolves to real artifacts before proceeding.
2. **Prompt empty / only "generate demo guide"** → derive from the **current working context**, in this order until one yields signal: active task list / workflow goal → `git status` + `git diff` (staged and unstaged) + branch name → recent commits vs the main branch → any in-progress plan/spec/release-note.
3. **No usable signal** → **STOP and `AskUserQuestion`**: _"Which feature should I generate the demo guide for?"_ Offer the best 2-4 candidates you did find plus free-text. NEVER pick one silently.

State the resolved scope and its source in one line (e.g. `Scope: <feature> — derived from branch diff (7 changed files)`).

**0.2 Load the output contract BEFORE gathering.** Read `references/demo-guide-template.md` — the document structure, the per-case block, the proof rungs, the storage-block field map, and the translation/HTML rules. The shape of the guide decides what you must collect; improvising it from memory guarantees a thin case block. **If the file is missing** (partial distribution, vendored copy, incomplete mirror sync), degrade **out loud, never silently**: say which file is absent in one line and run on the inline contract in this file (Step 6's four mandatory parts, Step 7's proof ladder). The guide is still owed in full; only the elaboration is lost.

**0.3 Size the target into a tier (count, do not estimate).** In-scope **files**, distinct user-facing **capabilities/flows**, distinct **modules/bounded contexts** (`docs/project-config.json` → modules), and **changed lines** where a diff exists. First row whose trigger matches, top-down. Announce it: `Scope: S2 · Multi — 14 files, 3 capabilities → 3 story groups`.

| Tier             | Trigger (first match wins)                             | Story groups        | How the work runs                            |
| ---------------- | ------------------------------------------------------ | ------------------- | -------------------------------------------- |
| **S0 · Point**   | One case, one bug fix, one screen                      | 1                   | Inline, case by case                         |
| **S1 · Small**   | < 10 in-scope files, one capability                    | 1                   | Inline, case by case                         |
| **S2 · Multi**   | ≥ 10 files **OR** ≥ 2 capabilities/flows/contexts      | 2–6                 | Inline, story group by story group           |
| **S3 · Large**   | > 40 files **OR** > 6 story groups                     | 6–12                | One sub-agent per group, front-loaded writes |
| **S4 · Program** | Whole product · multi-service · "demo the whole thing" | Grouped per context | Group agents → context synthesis → spine     |

> Thresholds are the framework's existing map-reduce ladder (`SYNC:systematic-review-batching`: < 10 sequential · ≥ 10 batch · > 6 categories or > 40 files hierarchical) and match `/understand`'s tiers deliberately. — why: a feature that gets understood and then demoed must be partitioned the same way twice, not by two competing maps.

**Tier is a SHAPE dial, not a depth dial.** It changes how many story groups exist and how the work is dispatched. It NEVER removes a case part, a proof rung, or the storage explanation.

**0.4 Decompose into story groups, then task the work — BEFORE any deep read.**

- **A story group is a demoable unit** — one user-facing capability whose cases can be staged in one sitting, ≤ 8 files or ≤ 2000 diff-lines. Decomposition axis, first rung yielding ≥2 cohesive groups: **capability / user story** → **end-to-end flow** → **module / bounded context** → **screen or endpoint cluster** (last resort, labelled _"structural grouping — not a story boundary"_). Record which rung you landed on. Tier S0/S1 → exactly one group.
- **[BLOCKING] Create the task list BEFORE gathering.** `TaskList` FIRST — an interrupted or compacted run **resumes its tasks, never duplicates them**. Then one task per story group plus the fixed tasks: _size & decompose · understand-gate · scope-wide gather · open guide + ledger · {one per group} · proof & transparency · validate_. Exactly one `in_progress`. **A group task completes ONLY when that group's block is on disk** — evidence is the path plus the cases it carries, never a summary in context. — why: a run that dies mid-guide must show exactly where it stopped.

## Step 1 — Understand the Feature FIRST **[BLOCKING GATE]**

**No demo step, no expected result, and no storage claim is written before this gate clears.** Investigation is not a preamble to the guide — it is the thing that makes the guide true.

**The comprehension bar — answer all six with `file:line`, for each story group:**

1. **What capability does this deliver, and what did the system do before it?** The before → after in _behaviour_ terms — this is what the demo's expected result must discriminate against.
2. **Which entity/aggregate owns the state the feature changes, and which field/column/table holds it?** Read the entity, the mapping/configuration, and the migration — not the property name.
3. **What is the end-to-end flow?** Entry point (screen/endpoint/job) → validation → handler/domain rule → persistence → the read path that renders the outcome the presenter will point at.
4. **Which business rule or invariant makes the expected result correct, and where is it enforced?** This is what a stakeholder's _"but what if…"_ attacks.
5. **What preconditions must exist, and which REAL user path stages each?** Roles, configuration, seed data, prior state — every one reachable through actions a user could actually perform.
6. **What proves it?** The REAL `TC-*` / test IDs covering each case, which of them are runnable in this environment, and which cases have none.

**Cannot answer one? Keep investigating — or delegate. NEVER paper over the gap with a plausible-looking step.**

| The gate needs…                                                       | Invoke                                 | Feeds                                         |
| --------------------------------------------------------------------- | -------------------------------------- | --------------------------------------------- |
| Where the feature's files even are, across a large or unfamiliar repo | `/scout`                               | Step 0.4 group decomposition + file lists     |
| How the existing feature actually works, beyond what one read shows   | `/investigate`                         | Bar Q1 · Q3 · Q4 → the storage/solution block |
| Why a fixed defect now behaves differently (bug-fix demo)             | `/debug-investigate`                   | Bar Q1's before → after discriminator         |
| The call/flow chain and which read path renders the outcome           | `/graph-trace` · `/graph-blast-radius` | Bar Q3 · the "where to look" demo step        |
| Which spec owns the capability, when finding it is itself the problem | `/spec-index` · `/spec`                | Bar Q6 → REAL `TC-*` IDs                      |

1. **Read-only delegates ONLY.** NEVER invoke a skill that mutates files or issues findings/verdicts (`/fix`, `/changes-review`, `/code-review`, `/why-review`, `/plan-execute`) — this skill emits a script, not a verdict, and mutates nothing but its own output.
2. **MUST ATTENTION delegate on evidence of need — NEVER by reflex.** Try read + grep + trace first, within the group's budget. Announce each delegation in one line and record it in the guide header: `Delegated: /investigate — Story B mechanics`. — why: the reader calibrates on the provenance chain exactly as on a grep-derived claim.
3. **A delegate's output is INPUT, never a finished block.** Re-verify every claim at `file:line` before it enters the guide; a `TC-*` ID that arrives through a delegate is still one you must have read yourself. The anti-hallucination bar does not relax by passing through another skill.
4. **At tier S3+, delegation happens INSIDE the group's sub-agent**, never in the orchestrator. — why: delegating from the orchestrator pulls a whole investigation transcript into the one context the grouping exists to protect.

**Gate exit — write the Understanding Brief to disk before Step 2 ends:** per story group, the six answers with their `file:line` anchors, the delegations used, and any question you could NOT answer (named as a blocker, never left blank). This brief is what Steps 4, 6 and 7 are written from — never memory.

## Step 2 — Gather the Five Inventories (portable discovery)

Read `docs/project-config.json` (and the project-reference docs it points to) to locate — do NOT hardcode: **source roots** (entities, handlers, migrations, models), **spec / feature-doc location** (canonical stories, ACs, `TC-*` IDs), **test locations** (integration/unit/e2e — the ground truth of "what is proven"), **release-notes / changelog / PBI-story** dirs, and **run/test commands**. This skill runs on repos it has never seen; a hardcoded framework path is a guess wearing a citation.

Each inventory walks its ladder top-down and **records the rung it landed on** — the reader calibrates on it. **Every ladder ends in a stated blocker; none has a rung of invention.**

1. **Story & test-case inventory** (feeds the story map, §Quick-reference). The main user-facing capabilities in scope, each as _As a … I want … so that …_, plus the REAL cases proving each — spec `TC-*` IDs and/or the integration/unit/e2e `it` / `[Fact]` / scenario names. Reconcile