Codex compatibility note:
- Invoke
$skill-name: load the registered .agents/skills/<name>/SKILL.md and execute it with Codex tools; no separate Skill tool or Claude mode switch is needed. When a workflow step or another skill names a skill, read that file in full yourself (every line, with no line limit; in parts only when output is cut off): a skill whose implicit invocation is off is never loaded for you. Author .claude/**; mirrors are generated.
- Track steps before execution and keep progress/evidence current. Explicit skill requests execute their protocol. Use the native question tool for required questions.
- Map foreign tool names to available host capabilities. A name mismatch needs no approval; an actually unavailable required capability stops with its step/evidence and a user question before adaptation.
- Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required
spawn_agent subagent(s) for that task.
- Preserve protocol order unless the user approves a deviation. Workflows use
$start-workflow: gates stay fixed; other steps may flex with logged reasons and evidence.
[BLOCKING] Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval. Inside a workflow run, $start-workflow → Workflow-step mode bounds this rule.
[BLOCKING] Before each step or sub-skill call, update todo 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.
Quick Summary
Goal: Investigate an in-scope feature end-to-end, then produce a stakeholder-ready, proof-carrying demo guide with real stories and profile-defined canonical identities linked to actual test/executor or approved manual-QC evidence, runnable user flows, domain storage/solution, and honest proof levels — UI-first, with technical cases in the closing appendix — so presenters can show behaviour, explain its data, and never claim unearned proof.
Summary: Read this if nothing else.
- Purpose: MUST ATTENTION investigate before scripting; prove behaviour, user path, storage, and solution with
file:line; ALWAYS state blockers instead of inventing missing evidence.
- Main steps (in order): MUST ATTENTION (0) resolve scope → load output + configured spec contract → size S0–S4 → decompose → create todos; (1) clear the six-question gate + write the Understanding Brief; (2) gather five inventories; (3) map/persist canonical identities to actual carriers + classify channels; (4) trace storage/solution; (5) open guide + ledger and accumulate; (6) write four-part cases; (7) compose the task block at the top; (8) assign proof rungs + transparency; (9) validate.
- Case contract: setup + numbered flow + discriminator + domain storage/solution + proof rung/chain. UI cases lead each story; technical cases keep full rigour in the closing appendix.
- Modes and boundaries:
feature-or-scope, --context, --output, --lang, --html, --stories, --estimate; only --estimate or an explicit estimation instruction names the estimate target — the demo scope never does; --lang emits a translated copy and --html follows post-approval Artifact flow; a no-front-end project names its primary demo surface; delegates gather read-only input only; secrets are redacted; deferred work is named in the header and chat summary.
Workflow:
- Resolve Scope, Load Contract, Size & Create Todos — prompt → context → ASK; read the template and configured spec contract; size S0–S4; decompose into story groups; create todos BEFORE the first deep read.
- Understand the Feature FIRST [BLOCKING] — clear the comprehension bar; use read-only gathering delegates only when needed; write the Understanding Brief.
- Gather the Five Inventories — discover through
docs/project-config.json; record each ladder's landing rung.
- Map Stories → Cases + Classify the Demo Channel — preserve profile-defined canonical identities and map them to verified test/executor evidence; name gaps and tag every case 🖥️ UI or 🔧 technical; under no-front-end, UI means the declared primary surface (Step 3.1).
- Trace Domain Storage & Solution — per case, identify persisted/changed data, owner, migration/handler, consuming rule, and
file:line evidence.
- Open the Guide + Ledger, Accumulate — write the spine first; add one block per story group; update the ledger as each lands.
- Write Each Case — setup → numbered flow → discriminator → domain storage/solution.
- Compose the Task Block — prepend a copy-paste-ready task at the very top: purpose, overall requirements, ALL acceptance criteria / user stories, authorization requirements, and a bottom-up estimate (effort points + man-days) per
SYNC:estimation-framework, sized over the estimate target only — the current changes by default, the target the user names for estimation, or (no change set in scope) the labelled demo scope — never silently the entire feature.
- Prove — assign the proof rung and write the test-execution transparency note.
- Validate — pass the gate below before declaring done.
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.
- THE GUIDE OPENS WITH A COPY-PASTE-READY TASK. Before the demo guide body, the document carries a task block (Step 7) a developer pastes straight into the tracker: purpose/business value · overall requirements (in/out of scope) · ALL acceptance criteria and user stories · authorization requirements (or an explicit
None) · estimation with effort points AND man-days derived bottom-up per SYNC:estimation-framework. Its content is sourced, never invented — copied from the governing spec/task where one exists, else derived from the traced cases with the source stated. — why: the demo and the task record describe the same item; a developer who must re-type it by hand ends up with two different truths.
- Scope precedence is prompt → current context → ASK. An explicit feature in the prompt wins; else derive from current work; else
ask user question tool — 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.
- DEMO THROUGH THE UI — the audience is a normal user / QC, not an engineer. Every main case is staged AND observed in the product's front-end. A case whose steps or expected result need an API client, CLI, script, manual job/queue trigger, DB query, log tail, or config edit is a 🔧 technical case: marked as such and collected in the closing
Appendix — Technical demo (non-UI) (after the last story, before the transparency note), NEVER among the important cases to test. Resolve the front-end rung FIRST (Step 3.1) — a project with no front-end states No front-end in this project — primary demo surface is {API / CLI / library / background job}, and that surface REPLACES "front-end" throughout this rule. — why: the room believes what it watches happen in the app; a terminal-driven step proves the code to engineers and proves nothing to the stakeholders the guide was written for.
- PROOF IS EARNED, NEVER ASSERTED. Every case sits on one of the four proof rungs (Step 8), and
✅ ran is licensed only by a configured test/executor or explicitly approved manual-QC carrier executed this session with its command/procedure and inspected result recorded. There is no fifth rung: a case you cannot place is a stated blocker.
- REAL IDENTITIES ONLY — NEVER invent a canonical or test ID. Use the configured native case identity and record actual test/executor references separately; use strict
TC-* identities only when neither config nor required project references establishes a native profile. A story with no proving carrier says "no verified carrier 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-quality-review, $plan --mode=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.
Contents
Demo Guide — Investigate-First, Proof-Carrying Demo Script
You are an investigator first, a presenter's coach second — the order is the point.
- Investigate: identify capability/before→after, state owner, click→persistence→display flow, and governing rule. Read the code; NEVER infer persistence from a name.
- Coach: provide a live real-user script, old-behaviour discriminator, and honest trace-vs-test proof statement.
Success bar: the presenter can stage preconditions without asking anyone, run every case without improvising, explain where data is stored and why it is correct, and distinguish green tests from trace-only demos. Otherwise it 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, tasks, or just a diff).
Invocation
$demo-guide [feature-or-scope] [--context] [--output path] [--lang xx] [--html] [--stories "A,B"] [--estimate "<target>"]
| Flag / arg |
Meaning |
feature-or-scope |
Named feature, spec title, task/story id, path, or free-text scope. Highest precedence. Sets the DEMO scope only, never the estimate target. |
--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. |
--estimate "<target>" |
Name the estimate target (story, task/story id, files, slice, or whole feature) — Step 7 rung 1. Absent → current changes. |
Step 0 — Resolve Scope, Load the Contract, Size & Create Todos (cheap — costs seconds)
0.1 Resolve scope (prompt → context → ASK). Apply this defining precedence:
- Prompt names scope → use it; normalize to a spec, task/story ID, changed files, or keywords; confirm real artifacts.
- Prompt empty / only "generate demo guide" → derive current context until signal: active task/workflow goal →
git status + staged/unstaged git diff + branch → recent commits vs main → in-progress plan/spec/release-note.
- No usable signal → STOP and
ask user question tool: "Which feature should I generate the demo guide for?" Offer 2-4 found candidates plus free text. NEVER pick 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 and spec contracts BEFORE Step 1. Read references/demo-guide-template.md for structure, case blocks, proof rungs, storage fields, and translation/HTML rules. If missing, name the absent file and use this file's inline Step 6–8 contract; still deliver the full guide, with only template elaboration unavailable. Read docs/project-config.json and routed spec references to resolve the case profile before asking what proves a case:
| Evidence |
Case contract |
Explicit specArtifacts profile in config |
Use its canonical root, sections, identities, carriers, and declared mapping relation; consult routed references for meaning. |
| No machine profile, but required references define a native model |
Use the documented native owner, identities, carriers, and mapping relation. |
| Neither config nor references defines a native model |
Use the strict TC-* identity and Section 8 default, with its one-TC-to-many-tests mapping. |
For a native profile, MUST ATTENTION preserve owner-qualified scenario identity and variants exactly; map each to actual test/executor or explicitly approved manual-QC carriers and inspected assertions or observed outcomes. Derive cardinality only from the declared contract and verified artifacts. NEVER treat an aggregate pass as proof for uninspected rows; leave their result unknown or blocked. Test names and guide-local labels are references, not canonical IDs; never flatten namespaces, invent IDs, create a second registry, or assume one-to-one mapping. Conflicts or unknown mappings remain blockers.
0.3 Size the target into a tier (count, do not estimate). Count in-scope files, user-facing capabilities/flows, modules/bounded contexts (docs/project-config.json → modules), and changed lines when a diff exists. Use the first matching row top-down, highest tier first. S0 is eligible only when no larger-scope trigger matches; an explicit point request does not override measured scale. Provisional grouping is a cheap scope signal; if decomposition later exceeds the selected tier, promote and announce the tier before dispatch. Announce it: Scope: S2 · Multi — 14 files, 3 capabilities → 3 story groups.
| Tier |
Trigger (first match wins) |
Story groups |
How the work runs |
| S4 · Program |
Whole product · multi-service · "demo the whole thing" |
Grouped per context |
Group agents → context synthesis → spine |
| S3 · Large |
> 40 files OR > 6 story groups |
6–12 |
One sub-agent per group, front-loaded writes |
| S2 · Multi |
≥ 10 files OR ≥ 2 capabilities/flows/contexts |
2–6 |
Inline, story group by story group |
| 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 |
These tiers govern demo story grouping and dispatch. Review assignments follow SYNC:systematic-review-batching from risk, related flows, working-set fit and delegation cost; a demo tier does not prescribe the review topology.
Tier is a SHAPE dial, not depth: it changes group count and dispatch, but NEVER removes a case part, proof rung, or storage explanation.
0.4 Decompose into story groups, then create the todos — BEFORE any deep read.
- A story group is a demoable unit — one user-facing capability staged in one sitting, ≤ 8 files or ≤ 2000 diff-lines. Choose the first decomposition rung yielding ≥2 cohesive groups: capability / user story → end-to-end flow → module / bounded context → screen or endpoint cluster (last resort: "structural grouping — not a story boundary"). Record the rung. S0/S1 → exactly one group. A 🔧 technical case NEVER forms its own group; it goes to the closing appendix (Step 3.1) — why: a group must be showable to a user.
- [BLOCKING] Create the todo list BEFORE gathering. the current task list FIRST; interrupted/compacted runs resume todos, never duplicate them. Create one todo per group plus: size & decompose · understand-gate · scope-wide gather · open guide + ledger · proof & transparency · validate. Exactly one
in_progress. A group todo completes ONLY when its block is on disk; evidence is the path plus its cases, not a context summary — why: an interrupted run must show its exact stopping point.
Step 1 — Understand the Feature FIRST [BLOCKING GATE]
No demo step, expected result, or storage claim before this gate clears. Investigation makes the guide true.
Comprehension bar — answer all six with file:line for each story group:
- What capability is delivered, and what did the system do before? State the before → after behaviour; the expected result must discriminate it.
- Which entity/aggregate owns the changed state, and which field/column/table holds it? Read entity, mapping/configuration, and migration — not the property name.
- What is the end-to-end flow? Entry screen/endpoint/job → validation → handler/domain rule → persistence → read path rendering the presenter's outcome.
- Which business rule/invariant makes the result correct, and where is it enforced? This is the stakeholder's "but what if…" test.
- What preconditions exist, and which REAL user path stages each? Roles, configuration, seed data, and prior state must be user-reachable.
- What proves it? The configured canonical owner/scenario identity (plus variant when defined) mapped to the actual test/executor or explicitly approved manual-QC carrier and its inspected assertion/observed outcome; runnable status here and cases with no carrier.
Cannot answer one? Keep investigating or delegate. NEVER paper over the gap with a plausible step.
| The gate needs… |
Invoke |
Feeds |
| Where the feature's files even are, across a large or unfamiliar repo |
$investigate |
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) |
$investigate --mode=debug |
Bar Q1's before → after discriminator |
| The call/flow chain and which read path renders the outcome |
$graph-code --mode=trace · $graph-code --mode=blast-radius (optional hints) |
Bar Q3 · the "where to look" demo step |
| Which spec owns the capability, when finding it is itself the problem |
$spec [mode=index] · $spec |
Bar Q6 → canonical identity + actual carrier |
- Read-only delegates ONLY. NEVER invoke a skill that mutates files or issues findings/verdicts (
$fix, $changes-review, $code-quality-review, $why-review, $plan --mode=execute) — this skill emits a script, not a verdict, and mutates nothing but its own output.
- 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.
- A delegate's output is INPUT, never a finished block. Re-verify every claim at
file:line before it enters the guide; a canonical identity or executor reference that arrives through a delegate is still one you must verify yourself. The anti-hallucination bar does not relax by passing through another skill.
- 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. For each group, include six answers with file:line, delegations, and every unanswered question as a named blocker, never blank. Steps 4, 6, and 7 use this brief, never memory.
Step 2 — Gather the Five Inventories (portable discovery)
Use the same docs/project-config.json and required project-reference docs to locate (do NOT hardcode) source roots (entities, handlers, migrations, models), spec/feature-doc locations and profiles (canonical owners, sections, identities, carriers, and declared mapping relation), test locations (integration/unit/e2e — ground truth of "what is proven"), release/changelog/task-story dirs, and run/test commands. This skill runs on unfamiliar repos; a hardcoded framework path is a guess wearing a citation.
Use the case contract resolved in Step 0.2 throughout the inventories and story map; do not reselect or reinterpret it per source.
Each inventory walks its ladder top-down and records its landing rung. Every ladder ends in a stated blocker; none has an invention rung.
- Story & case-evidence inventory (feeds the story map and §Quick-reference). The main user-facing capabilities in scope, each as As a … I want … so that …, plus the configured canonical case identities and actual test/executor or explicitly approved manual-QC carriers proving each. Under the strict default, preserve the spec
TC-* identity and link its real test carriers. Follow the declared mapping relation; never merge canonical IDs with executor names into one namespace or assume a one-to-one mapping. Ladder: canonical specs → actual test/executor sources → tasks/release notes/commit messages → the diff itself → state that no story source exists.
- Domain storage & solution inventory (feeds each case's fourth part). Per case: the persisted field/column/table, the owning entity/value object, the migration that added or altered it, the value actually written (anchored/computed), and the rule/method/invariant that consumes it. Ladder: entity + mapping + migration read → graph trace of the writer/reader → schema dump → state the blocker.
- Demo path & setup inventory (feeds setup/preconditions and the numbered steps). The real user path to each precondition: roles/permissions, configuration flags, seed or fixture entry points, which app/screen/endpoint, and what input. Ladder: existing seeders/fixtures → e2e test setup → manual path traced through the UI/API code → state that the precondition cannot be staged.
- Proof inventory (feeds the proof rung per case). Which configured tests/executors or approved manual-QC carriers exist, which are runnable here (resolve the command/procedure — never guess it), and what actually ran or was observed this session. Ladder:
project-config.json commands → the CI workflow's own commands/procedures → the test-runner manifest (package.json scripts, *.csproj, Makefile) → state that no carrier or run procedure could be resolved.
- Discriminator inventory (feeds every expected result). Per case, the value/state that would have been WRONG under the old behaviour — from the diff, the fixed defect, the spec's AC, or the test's assertion. Ladder: the test assertion → the diff's before/after → the spec AC → state that the discriminator is unknown rather than writing "it succeeds".
[SECURITY] Record every command, credential, and account in placeholder form at the moment of collection — not at write time. Environment variables, connection strings, tokens, keys, passwords, and customer identifiers are referenced by NAME and rendered <redacted:…>; demo accounts are named by role (<demo user: approver>), never by real login. This is the point where a secret would first enter context, so it is the point that must refuse it.
Read the code path from the stored field to the reader that solves the case; optionally, when .code-graph/graph.db exists, python .claude/scripts/code_graph trace <entity-or-handler> --direction both --json can hint at the flow (it may be stale — verify at file:line). The "how the domain solves the feature" claim is backed by file:line evidence, not guesswork.
Step 3 — Map Stories → Cases (persist the map)
- Main user story = user-facing capability/outcome. Prefer spec stories; otherwise synthesize one per distinct capability from ACs/tests. Keep minor variants under cases; do not inflate the count.
- Cases per story = presentation cases traced to profile-defined canonical identities and actual proving carriers — NEVER invent or repurpose IDs. A story without a verified carrier is a coverage gap to report, never a plausible ID.
Write the story → case map to disk before any case block; cross-check the full changed-file list so no main area is missed — why: the map is the coverage contract, and context-only work can vanish at cutoff.
3.1 Classify every case by DEMO CHANNEL — UI-first [BLOCKING before any case block is written].
The reader is a normal user / QC driving the running app — no terminal, API client, database console, or log tail. Classify every mapped case into exactly ONE channel; the channel determines placement.
FIRST resolve the PROJECT's primary demo surface — one rung, stated once, before classifying cases. Discover whether a front-end exists; record the landing rung and repeat it verbatim in the guide header.
| Rung |
Resolve when |
What it changes below |
| Front-end present |
a discriminating signal resolves to a real user-facing app |
Default — everything below applies exactly as written. |
No front-end in this project — primary demo surface is {API / CLI / library / background job} |
no signal resolves |
That surface REPLACES the front-end throughout — including the channel table below: read "front-end" as that surface and "non-UI" as "not that surface", so its cases are the main-body channel, ordered first, and the appendix holds only what is not demoable on that surface either. The main-channel marker stays 🖥️, but the WORD UI is replaced by the surface name everywhere the split is written. |
Discriminating signals (docs/project-config.json): modules[*].kind (front-end/app/web vs library/service) · e2eTesting.framework ("none" means no browser surface) · styling.guideDoc · designSystem.appMappings. NEVER test framework.frontendPatternsDoc: it is a scaffold default and proves nothing. Whichever signal decides, state the rung; NEVER switch silently — why: without it, backend, CLI, library, and API products get an empty main body, an all-appendix guide, and a false thin-surface finding.
| Channel |
Test (first failure decides) |
Placement |
| 🖥️ UI case — the demo |
Staged and observed entirely through the product's front-end: screens, forms, clicks, navigation, visible output |
Main body, inside its story group, ordered first |
| 🔧 Technical case |
ANY step or expected result needs a non-UI surface — HTTP/API client, CLI, script, manual job/queue trigger, DB query, log or file inspection, config edit |
Closing ## Appendix — Technical demo (non-UI) — after every story, before the transparency note |
- UI cases carry the demo; technical cases are the appendix. Order each story's cases UI-first, and NEVER let a technical case open a story, head the quick-reference table, or count as a main case to test. — why: the room believes what it watches happen in the app.
- Hybrid = UI case. A case demoed on screen whose data can ALSO be confirmed in the DB or logs stays a UI case — put that confirmation on its own
Deeper confirmation (optional, non-UI) line, NEVER as a numbered demo step and NEVER on the proof chain. — why: every numbered step must be runnable by the presenter on screen with no tooling the audience has; and the proof chain is typed as file:line links a challenger can walk, so a runtime action ("query orders after clicking Save") on that line is an entry the auditor cannot open.
- A story whose ONLY demonstration is technical is a stated finding. Record
no UI demo path — technical only in the story header and route its cases to the appendix. NEVER invent a screen, button, or admin page to make a case look UI-demoable. Silent under the no-front-end rung — a project with no front-end by design has no missing UI path to report; there the finding fires only when a case is not demoable on the project's primary surface either. — why: an invented surface fails live, and the audience discovers it before you do.
- Announce the split in the guide header —
Cases: 11 🖥️ UI · 3 🔧 technical (appendix). Under the no-front-end rung the split counts the primary surface as the main channel, and a large appendix is NOT a thin-surface finding — the stated rung already explains it. — why: for a product that HAS a front-end, a guide that is mostly appendix is telling the team the feature's user-visible surface is thin — a finding worth surfacing, not a formatting detail.
- A technical case keeps the FULL four-part block and its proof rung — it is demoted in ORDER and PROMINENCE, never in rigour. It obeys every per-case rule below: the four parts, real-user-path setup with no faked state, the
file:line storage claim, the proof rung and chain; only its observation surface may be non-UI. — why: the appendix is a placement, not a lower evidence bar — and "not a main case" must never be read as "not bound by the per-case rules".
Step 4 — Trace Domain Storage & Solution (the distinctive step)
For each case — UI and 🔧 technical — read the owning code and answer both questions with file:line evidence:
- How is domain data stored or changed? Identify persisted field(s)/column(s)/table, owning value object/entity, migration, anchored/computed value, and additive/nullable/backfilled status. Read entity, DTO mapping, and migration — NEVER infer persistence from names.
- How does the domain solve the feature? Identify the rule/method/invariant consuming that data to produce the outcome (resolver/derivation/gate), and why storage makes it correct — including edge cases, legacy fallback, and cross-tier parity.
For a display-only case, state explicitly that persistence does not change and describe the representation (computed value/shape and why correct). "No storage change" is valid; an empty block is not.
Step 5 — Open the Guide + Ledger, Accumulate Story by Story
Create the guide file BEFORE case one and append as you produce it. NEVER hold the whole guide in context for one final write.
Write order is fixed: title + a <!-- task:START --> / <!-- task:END --> placeholder marked pending (filled in Step 7) → header — scope/source, sources, delegations, tier/group count, group ledger rows pending, and empty Appendix — Technical demo (non-UI) heading → each group (trace → write main cases → append 🔧 technical cases to the appendix → mark its ledger row written with main / technical split → complete its todo) → guide-level sections (storage summary, quick-reference table, transparency note) from written blocks → chat summary. NEVER hold more than the current group; read finished blocks from disk — why: the appendix is last in the document but technical cases are written per group, preventing context loss.
After a cutoff, compaction, or resume: the current task list → read the ledger → verify every written row against the filesystem — a group's cases live in TWO places, so check BOTH: the file exists AND carries that group's main-channel cases AND its 🔧 technical cases in the appendix; an absent or truncated block in either location resets the row to pending → re-read the contract and the Understanding Brief → continue at the first unfinished group. NEVER restart a finished group and never re-derive a written block from memory.
[NO SILENT TRUNCATION] If any cap, budget, or interruption leaves part of the resolved scope uncovered, name what was deferred or dropped in the guide header AND in the chat summary — "Story D (bulk import, 9 cases) deferred — not covered by this guide." — why: bounded coverage that reads as complete coverage sends a presenter into a room unprepared for the question nobody examined.
Write location — the demo guide is a DELIVERABLE, not a working artifact. Write it to the project's demo-guide dir (Configuration); it is shared and version-controlled. This deliberately differs from $understand, whose report is git-ignored — do NOT copy that rule here — why: a guide the team cannot find is unused.
Step 6 — Write Each Case (four mandatory parts)
Follow references/demo-guide-template.md. Per case — UI and 🔧 technical — the guide MUST contain:
- Setup / preconditions — exact state (roles, configuration, seed data, app/screen), staged through real user paths; never fake unreachable state. Secrets use
<redacted:…>, accounts use roles.
- Step-by-step demo flow — numbered, concrete click/action steps: actor, screen, input, and observation. Every 🖥️ UI step runs in the front-end; endpoint, command, query, or log inspection appears ONLY in a 🔧 technical appendix case. An untraceable step is a stated blocker, never an invented click.
- Expected result — observable discriminator: the value that would have been WRONG under old behaviour, not generic "it succeeds".
- How the domain stores/changes data + solves it — Step 4 in plain team language with
file:line anchors.
Order inside every story: 🖥️ UI cases first (happy path → variants → edge cases → legacy). 🔧 Technical cases are NOT inline; put them in the closing Appendix — Technical demo (non-UI) with the same four-part shape, after the last story — why: presenters read top-down.
Also include: scope/source header with {n} UI · {n} technical split, story groups, main case quick-reference table (canonical identity · actual carrier reference(s) · what it proves · proof rung — main-channel cases only), domain storage summary per story, closing technical demo appendix, and test-execution transparency note. Keep prose tight.
--lang given → emit a translated copy (prose translated; code identifiers, file:line, configured canonical IDs, executor references, and numeric values kept verbatim). --html given → follow the Artifact flow to render a self-contained runbook after the markdown is approved.
Step 7 — Compose the Task Block (top of the guide)
Purpose: a developer/PO copies this block straight into the work tracker (Jira/ADO/Linear) without re-typing anything. It sits above the demo-guide body, immediately under the document title, fenced by <!-- task:START --> / <!-- task:END --> so it can be selected and copied in one go.
[BLOCKING] SOURCE IT, NEVER INVENT IT. Fill every field from evidence already gathered in Steps 1–6:
- A governing task / spec / story exists (the business spec root — default
docs/specs/**; a specRoots.business.path entry in docs/project-config.json overrides the path — a task or story artifact, a tracker item found in Step 2) → copy its wording for requirements, stories, and acceptance criteria; normalize formatting only. Cite the source path in the block header.
- No such artifact → derive from the traced cases and code, and label the block
derived from code + demo cases this session — not yet reviewed by the PO.
- A field has no evidence → write the explicit negative (
None — no authorization behaviour in this item), NEVER a plausible filler. An invented acceptance criterion is worse than an absent one: it enters the tracker as a commitment nobody agreed to.
Mandatory fields (all present; an inapplicable one states why):
| Field |
Content |
Sourced from |
| Title + type |
One-line item title · Feature | Enhancement | Bug | Tech |
Resolved scope (Step 0.1) |
| Purpose / business value |
Why the item exists, for whom, and the outcome it buys — 2–4 sentences, no implementation detail |
Spec/task, or Step 1 bar Q1 (before → after) |
| Overall requirements |
What the item must deliver, as a short numbered list, plus explicit **In s |
|
…(truncated)
1---2name: demo-guide-43description: '[Documentation] Use when a workflow step or the user asks for demo guides and delivery walkthroughs linking stories and canonical cases to runnable flows and evidence.'4metadata:5 source: https://skillmd.com/skills/duc01226/demo-guide-46---78> Codex compatibility note:9> - Invoke `$skill-name`: load the registered `.agents/skills/<name>/SKILL.md` and execute it with Codex tools; no separate `Skill` tool or Claude mode switch is needed. When a workflow step or another skill names a skill, read that file in full yourself (every line, with no line limit; in parts only when output is cut off): a skill whose implicit invocation is off is never loaded for you. Author `.claude/**`; mirrors are generated.10> - Track steps before execution and keep progress/evidence current. Explicit skill requests execute their protocol. Use the native question tool for required questions.11> - Map foreign tool names to available host capabilities. A name mismatch needs no approval; an actually unavailable required capability stops with its step/evidence and a user question before adaptation.12> - Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required `spawn_agent` subagent(s) for that task.13> - Preserve protocol order unless the user approves a deviation. Workflows use `$start-workflow`: gates stay fixed; other steps may flex with logged reasons and evidence.14<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:START -->1516> **[BLOCKING]** Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval. Inside a workflow run, `$start-workflow` → Workflow-step mode bounds this rule.17> **[BLOCKING]** Before each step or sub-skill call, update todo tracking: set `in_progress` when step starts, set `completed` when step ends.18> **[BLOCKING]** Every completed/skipped step MUST include brief evidence or explicit skip reason.19> **[BLOCKING]** If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.2021<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:END -->2223## Quick Summary2425**Goal:** Investigate an in-scope feature end-to-end, then produce a stakeholder-ready, proof-carrying demo guide with real stories and profile-defined canonical identities linked to actual test/executor or approved manual-QC evidence, runnable user flows, domain storage/solution, and honest proof levels — UI-first, with technical cases in the closing appendix — so presenters can show behaviour, explain its data, and never claim unearned proof.2627**Summary:** Read this if nothing else.2829- **Purpose:** MUST ATTENTION investigate before scripting; prove behaviour, user path, storage, and solution with `file:line`; ALWAYS state blockers instead of inventing missing evidence.30- **Main steps (in order):** MUST ATTENTION (0) resolve scope → load output + configured spec contract → size S0–S4 → decompose → create todos; (1) clear the six-question gate + write the Understanding Brief; (2) gather five inventories; (3) map/persist canonical identities to actual carriers + classify channels; (4) trace storage/solution; (5) open guide + ledger and accumulate; (6) write four-part cases; (7) compose the task block at the top; (8) assign proof rungs + transparency; (9) validate.31- **Case contract:** setup + numbered flow + discriminator + domain storage/solution + proof rung/chain. UI cases lead each story; technical cases keep full rigour in the closing appendix.32- **Modes and boundaries:** `feature-or-scope`, `--context`, `--output`, `--lang`, `--html`, `--stories`, `--estimate`; only `--estimate` or an explicit estimation instruction names the estimate target — the demo scope never does; `--lang` emits a translated copy and `--html` follows post-approval Artifact flow; a no-front-end project names its primary demo surface; delegates gather read-only input only; secrets are redacted; deferred work is named in the header and chat summary.3334**Workflow:**35360. **Resolve Scope, Load Contract, Size & Create Todos** — prompt → context → ASK; read the template and configured spec contract; size S0–S4; decompose into story groups; create todos BEFORE the first deep read.371. **Understand the Feature FIRST [BLOCKING]** — clear the comprehension bar; use read-only gathering delegates only when needed; write the Understanding Brief.382. **Gather the Five Inventories** — discover through `docs/project-config.json`; record each ladder's landing rung.393. **Map Stories → Cases + Classify the Demo Channel** — preserve profile-defined canonical identities and map them to verified test/executor evidence; name gaps and tag every case 🖥️ UI or 🔧 technical; under no-front-end, UI means the declared primary surface (Step 3.1).404. **Trace Domain Storage & Solution** — per case, identify persisted/changed data, owner, migration/handler, consuming rule, and `file:line` evidence.415. **Open the Guide + Ledger, Accumulate** — write the spine first; add one block per story group; update the ledger as each lands.426. **Write Each Case** — setup → numbered flow → discriminator → domain storage/solution.437. **Compose the Task Block** — prepend a copy-paste-ready task at the very top: purpose, overall requirements, ALL acceptance criteria / user stories, authorization requirements, and a bottom-up estimate (effort points + man-days) per `SYNC:estimation-framework`, sized over the **estimate target only** — the current changes by default, the target the user names for estimation, or (no change set in scope) the labelled demo scope — never silently the entire feature.448. **Prove** — assign the proof rung and write the test-execution transparency note.459. **Validate** — pass the gate below before declaring done.4647**Key Rules (the contract):**4849- **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.50- **THE GUIDE OPENS WITH A COPY-PASTE-READY TASK.** Before the demo guide body, the document carries a task block (Step 7) a developer pastes straight into the tracker: purpose/business value · overall requirements (in/out of scope) · **ALL** acceptance criteria and user stories · authorization requirements (or an explicit `None`) · estimation with **effort points AND man-days** derived bottom-up per `SYNC:estimation-framework`. Its content is **sourced, never invented** — copied from the governing spec/task where one exists, else derived from the traced cases with the source stated. — why: the demo and the task record describe the same item; a developer who must re-type it by hand ends up with two different truths.51- **Scope precedence is prompt → current context → ASK.** An explicit feature in the prompt wins; else derive from current work; else `ask user question tool` — NEVER invent a feature.52- **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.53- **DEMO THROUGH THE UI — the audience is a normal user / QC, not an engineer.** Every main case is staged AND observed in the product's front-end. A case whose steps or expected result need an API client, CLI, script, manual job/queue trigger, DB query, log tail, or config edit is a **🔧 technical case**: marked as such and collected in the closing `Appendix — Technical demo (non-UI)` (after the last story, before the transparency note), NEVER among the important cases to test. **Resolve the front-end rung FIRST (Step 3.1)** — a project with no front-end states `No front-end in this project — primary demo surface is {API / CLI / library / background job}`, and that surface REPLACES "front-end" throughout this rule. — why: the room believes what it watches happen in the app; a terminal-driven step proves the code to engineers and proves nothing to the stakeholders the guide was written for.54- **PROOF IS EARNED, NEVER ASSERTED.** Every case sits on one of the four proof rungs (Step 8), and `✅ ran` is licensed **only** by a configured test/executor or explicitly approved manual-QC carrier executed this session with its command/procedure and inspected result recorded. There is no fifth rung: a case you cannot place is a **stated blocker**.55- **REAL IDENTITIES ONLY — NEVER invent a canonical or test ID.** Use the configured native case identity and record actual test/executor references separately; use strict `TC-*` identities only when neither config nor required project references establishes a native profile. A story with no proving carrier says *"no verified carrier covers this"* and is recorded as a coverage gap. — why: a fabricated ID retires a risk that is still live.56- **Cite `file:line` for every storage/behaviour claim** — read the entity, the mapping, and the migration. NEVER infer persistence from a field name.57- **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.58- **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-quality-review`, `$plan --mode=execute`).59- **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.60- **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.61- **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.62- **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.63- **Scale buys MORE STORY GROUPS, never FEWER PARTS per case.** *"Too big to demo properly"* is a conclusion this skill may never reach.6465**Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act.**6667---6869## Contents7071- [Quick Summary](#quick-summary)72- [Demo Guide — Investigate-First, Proof-Carrying Demo Script](#demo-guide--investigate-first-proof-carrying-demo-script)73- [Invocation](#invocation)74- [Step 0 — Resolve Scope, Load the Contract, Size & Create Todos (cheap — costs seconds)](#step-0--resolve-scope-load-the-contract-size--create-todos-cheap--costs-seconds)75- [Step 1 — Understand the Feature FIRST **\[BLOCKING GATE\]**](#step-1--understand-the-feature-first-blocking-gate)76- [Step 2 — Gather the Five Inventories (portable discovery)](#step-2--gather-the-five-inventories-portable-discovery)77- [Step 3 — Map Stories → Cases (persist the map)](#step-3--map-stories--cases-persist-the-map)78- [Step 4 — Trace Domain Storage & Solution (the distinctive step)](#step-4--trace-domain-storage--solution-the-distinctive-step)79- [Step 5 — Open the Guide + Ledger, Accumulate Story by Story](#step-5--open-the-guide--ledger-accumulate-story-by-story)80- [Step 6 — Write Each Case (four mandatory parts)](#step-6--write-each-case-four-mandatory-parts)81- [Step 7 — Compose the Task Block (top of the guide)](#step-7--compose-the-task-block-top-of-the-guide)82- [Step 8 — Prove (the proof ladder)](#step-8--prove-the-proof-ladder)83- [Step 9 — Validate](#step-9--validate)84- [Configuration](#configuration)85- [Integration with Other Skills](#integration-with-other-skills)86- [Closing Reminders](#closing-reminders)8788# Demo Guide — Investigate-First, Proof-Carrying Demo Script8990You are an **investigator first, a presenter's coach second** — the order is the point.9192- **Investigate:** identify capability/before→after, state owner, click→persistence→display flow, and governing rule. Read the code; NEVER infer persistence from a name.93- **Coach:** provide a live real-user script, old-behaviour discriminator, and honest trace-vs-test proof statement.9495> **Success bar:** the presenter can stage preconditions without asking anyone, run every case without improvising, explain where data is stored and why it is correct, and distinguish green tests from trace-only demos. Otherwise it is a wish-list, not a demo guide.9697Instructions, not documentation: this skill teaches HOW to build the guide from real project evidence, adapting to whatever the project actually has (specs, tests, tasks, or just a diff).9899## Invocation100101```102$demo-guide [feature-or-scope] [--context] [--output path] [--lang xx] [--html] [--stories "A,B"] [--estimate "<target>"]103```104105| Flag / arg | Meaning |106| ------------------ | -------------------------------------------------------------------------------------------------- |107| `feature-or-scope` | Named feature, spec title, task/story id, path, or free-text scope. Highest precedence. Sets the DEMO scope only, never the estimate target. |108| `--context` | Force "derive scope from current working context" (branch diff / staged + unstaged / active work). |109| `--output path` | Where to write the guide. Default: project demo-guide dir (see Configuration), else a temp file. |110| `--lang xx` | Also emit a translated copy in the given language (keep code identifiers/paths/IDs in English). |111| `--html` | After the markdown, offer/produce a self-contained HTML runbook (via the Artifact flow). |112| `--stories "A,B"` | Restrict to the named stories instead of all main stories. |113| `--estimate "<target>"` | Name the estimate target (story, task/story id, files, slice, or `whole feature`) — Step 7 rung 1. Absent → current changes. |114115## Step 0 — Resolve Scope, Load the Contract, Size & Create Todos (cheap — costs seconds)116117**0.1 Resolve scope (prompt → context → ASK).** Apply this defining precedence:1181191. **Prompt names scope** → use it; normalize to a spec, task/story ID, changed files, or keywords; confirm real artifacts.1202. **Prompt empty / only "generate demo guide"** → derive current context until signal: active task/workflow goal → `git status` + staged/unstaged `git diff` + branch → recent commits vs main → in-progress plan/spec/release-note.1213. **No usable signal** → **STOP and `ask user question tool`**: *"Which feature should I generate the demo guide for?"* Offer 2-4 found candidates plus free text. NEVER pick silently.122123State the resolved scope and its source in one line (e.g. `Scope: <feature> — derived from branch diff (7 changed files)`).124125**0.2 Load the output and spec contracts BEFORE Step 1.** Read `references/demo-guide-template.md` for structure, case blocks, proof rungs, storage fields, and translation/HTML rules. **If missing**, name the absent file and use this file's inline Step 6–8 contract; still deliver the full guide, with only template elaboration unavailable. Read `docs/project-config.json` and routed spec references to resolve the case profile before asking what proves a case:126127| Evidence | Case contract |128| --- | --- |129| Explicit `specArtifacts` profile in config | Use its canonical root, sections, identities, carriers, and declared mapping relation; consult routed references for meaning. |130| No machine profile, but required references define a native model | Use the documented native owner, identities, carriers, and mapping relation. |131| Neither config nor references defines a native model | Use the strict `TC-*` identity and Section 8 default, with its one-TC-to-many-tests mapping. |132133For a native profile, **MUST ATTENTION** preserve owner-qualified scenario identity and variants exactly; map each to actual test/executor or explicitly approved manual-QC carriers and inspected assertions or observed outcomes. Derive cardinality only from the declared contract and verified artifacts. **NEVER** treat an aggregate pass as proof for uninspected rows; leave their result unknown or blocked. Test names and guide-local labels are references, not canonical IDs; never flatten namespaces, invent IDs, create a second registry, or assume one-to-one mapping. Conflicts or unknown mappings remain blockers.134135**0.3 Size the target into a tier (count, do not estimate).** Count in-scope **files**, user-facing **capabilities/flows**, **modules/bounded contexts** (`docs/project-config.json` → modules), and changed lines when a diff exists. Use the first matching row top-down, highest tier first. S0 is eligible only when no larger-scope trigger matches; an explicit point request does not override measured scale. Provisional grouping is a cheap scope signal; if decomposition later exceeds the selected tier, promote and announce the tier before dispatch. Announce it: `Scope: S2 · Multi — 14 files, 3 capabilities → 3 story groups`.136137| Tier | Trigger (first match wins) | Story groups | How the work runs |138| --------------- | ------------------------------------------------------ | ------------------- | ----------------------------------------- |139| **S4 · Program**| Whole product · multi-service · "demo the whole thing" | Grouped per context | Group agents → context synthesis → spine |140| **S3 · Large** | > 40 files **OR** > 6 story groups | 6–12 | One sub-agent per group, front-loaded writes |141| **S2 · Multi** | ≥ 10 files **OR** ≥ 2 capabilities/flows/contexts | 2–6 | Inline, story group by story group |142| **S0 · Point** | One case, one bug fix, one screen | 1 | Inline, case by case |143| **S1 · Small** | < 10 in-scope files, one capability | 1 | Inline, case by case |144145> These tiers govern demo story grouping and dispatch. Review assignments follow `SYNC:systematic-review-batching` from risk, related flows, working-set fit and delegation cost; a demo tier does not prescribe the review topology.146147**Tier is a SHAPE dial, not depth:** it changes group count and dispatch, but NEVER removes a case part, proof rung, or storage explanation.148149**0.4 Decompose into story groups, then create the todos — BEFORE any deep read.**150151- **A story group is a demoable unit** — one user-facing capability staged in one sitting, ≤ 8 files or ≤ 2000 diff-lines. Choose the first decomposition rung yielding ≥2 cohesive groups: **capability / user story** → **end-to-end flow** → **module / bounded context** → **screen or endpoint cluster** (last resort: *"structural grouping — not a story boundary"*). Record the rung. S0/S1 → exactly one group. A 🔧 technical case NEVER forms its own group; it goes to the closing appendix (Step 3.1) — why: a group must be showable to a user.152- **[BLOCKING] Create the todo list BEFORE gathering.** the current task list FIRST; interrupted/compacted runs resume todos, never duplicate them. Create one todo per group plus: *size & decompose · understand-gate · scope-wide gather · open guide + ledger · proof & transparency · validate*. Exactly one `in_progress`. **A group todo completes ONLY when its block is on disk**; evidence is the path plus its cases, not a context summary — why: an interrupted run must show its exact stopping point.153154## Step 1 — Understand the Feature FIRST **[BLOCKING GATE]**155156**No demo step, expected result, or storage claim before this gate clears.** Investigation makes the guide true.157158**Comprehension bar — answer all six with `file:line` for each story group:**1591601. **What capability is delivered, and what did the system do before?** State the before → after behaviour; the expected result must discriminate it.1612. **Which entity/aggregate owns the changed state, and which field/column/table holds it?** Read entity, mapping/configuration, and migration — not the property name.1623. **What is the end-to-end flow?** Entry screen/endpoint/job → validation → handler/domain rule → persistence → read path rendering the presenter's outcome.1634. **Which business rule/invariant makes the result correct, and where is it enforced?** This is the stakeholder's *"but what if…"* test.1645. **What preconditions exist, and which REAL user path stages each?** Roles, configuration, seed data, and prior state must be user-reachable.1656. **What proves it?** The configured canonical owner/scenario identity (plus variant when defined) mapped to the actual test/executor or explicitly approved manual-QC carrier and its inspected assertion/observed outcome; runnable status here and cases with no carrier.166167**Cannot answer one?** Keep investigating or delegate. NEVER paper over the gap with a plausible step.168169| The gate needs… | Invoke | Feeds |170| ---------------------------------------------------------------------- | ----------------------------------- | -------------------------------------------- |171| Where the feature's files even are, across a large or unfamiliar repo | `$investigate` | Step 0.4 group decomposition + file lists |172| How the existing feature actually works, beyond what one read shows | `$investigate` | Bar Q1 · Q3 · Q4 → the storage/solution block |173| Why a fixed defect now behaves differently (bug-fix demo) | `$investigate --mode=debug` | Bar Q1's before → after discriminator |174| The call/flow chain and which read path renders the outcome | `$graph-code --mode=trace` · `$graph-code --mode=blast-radius` (optional hints) | Bar Q3 · the "where to look" demo step |175| Which spec owns the capability, when finding it is itself the problem | `$spec [mode=index]` · `$spec` | Bar Q6 → canonical identity + actual carrier |1761771. **Read-only delegates ONLY.** NEVER invoke a skill that mutates files or issues findings/verdicts (`$fix`, `$changes-review`, `$code-quality-review`, `$why-review`, `$plan --mode=execute`) — this skill emits a script, not a verdict, and mutates nothing but its own output.1782. **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.1793. **A delegate's output is INPUT, never a finished block.** Re-verify every claim at `file:line` before it enters the guide; a canonical identity or executor reference that arrives through a delegate is still one you must verify yourself. The anti-hallucination bar does not relax by passing through another skill.1804. **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.181182**Gate exit:** write the Understanding Brief to disk before Step 2 ends. For each group, include six answers with `file:line`, delegations, and every unanswered question as a named blocker, never blank. Steps 4, 6, and 7 use this brief, never memory.183184## Step 2 — Gather the Five Inventories (portable discovery)185186Use the same `docs/project-config.json` and required project-reference docs to locate (do NOT hardcode) **source roots** (entities, handlers, migrations, models), **spec/feature-doc locations and profiles** (canonical owners, sections, identities, carriers, and declared mapping relation), **test locations** (integration/unit/e2e — ground truth of "what is proven"), **release/changelog/task-story** dirs, and **run/test commands**. This skill runs on unfamiliar repos; a hardcoded framework path is a guess wearing a citation.187188Use the case contract resolved in Step 0.2 throughout the inventories and story map; do not reselect or reinterpret it per source.189190Each inventory walks its ladder top-down and **records its landing rung**. **Every ladder ends in a stated blocker; none has an invention rung.**1911921. **Story & case-evidence inventory** (feeds the story map and §Quick-reference). The main user-facing capabilities in scope, each as *As a … I want … so that …*, plus the configured canonical case identities and actual test/executor or explicitly approved manual-QC carriers proving each. Under the strict default, preserve the spec `TC-*` identity and link its real test carriers. Follow the declared mapping relation; never merge canonical IDs with executor names into one namespace or assume a one-to-one mapping. _Ladder:_ canonical specs → actual test/executor sources → tasks/release notes/commit messages → the diff itself → **state that no story source exists**.1932. **Domain storage & solution inventory** (feeds each case's fourth part). Per case: the persisted field/column/table, the owning entity/value object, the migration that added or altered it, the value actually written (anchored/computed), and the rule/method/invariant that consumes it. _Ladder:_ entity + mapping + migration read → graph trace of the writer/reader → schema dump → **state the blocker**.1943. **Demo path & setup inventory** (feeds setup/preconditions and the numbered steps). The real user path to each precondition: roles/permissions, configuration flags, seed or fixture entry points, which app/screen/endpoint, and what input. _Ladder:_ existing seeders/fixtures → e2e test setup → manual path traced through the UI/API code → **state that the precondition cannot be staged**.1954. **Proof inventory** (feeds the proof rung per case). Which configured tests/executors or approved manual-QC carriers exist, which are runnable here (resolve the command/procedure — never guess it), and what actually ran or was observed this session. _Ladder:_ `project-config.json` commands → the CI workflow's own commands/procedures → the test-runner manifest (`package.json` scripts, `*.csproj`, `Makefile`) → **state that no carrier or run procedure could be resolved**.1965. **Discriminator inventory** (feeds every expected result). Per case, the value/state that would have been WRONG under the old behaviour — from the diff, the fixed defect, the spec's AC, or the test's assertion. _Ladder:_ the test assertion → the diff's before/after → the spec AC → **state that the discriminator is unknown** rather than writing "it succeeds".197198> **[SECURITY]** Record every command, credential, and account in **placeholder form** at the moment of collection — not at write time. Environment variables, connection strings, tokens, keys, passwords, and customer identifiers are referenced by NAME and rendered `<redacted:…>`; demo accounts are named by **role** (`<demo user: approver>`), never by real login. This is the point where a secret would first enter context, so it is the point that must refuse it.199200> Read the code path from the stored field to the reader that solves the case; optionally, when `.code-graph/graph.db` exists, `python .claude/scripts/code_graph trace <entity-or-handler> --direction both --json` can hint at the flow (it may be stale — verify at `file:line`). The "how the domain solves the feature" claim is backed by `file:line` evidence, not guesswork.201202## Step 3 — Map Stories → Cases (persist the map)203204- **Main user story** = user-facing capability/outcome. Prefer spec stories; otherwise synthesize one per distinct capability from ACs/tests. Keep minor variants under cases; do not inflate the count.205- **Cases per story** = presentation cases traced to profile-defined canonical identities and actual proving carriers — NEVER invent or repurpose IDs. A story without a verified carrier is a **coverage gap to report**, never a plausible ID.206207Write the story → case map to disk before any case block; cross-check the full changed-file list so no main area is missed — why: the map is the coverage contract, and context-only work can vanish at cutoff.208209**3.1 Classify every case by DEMO CHANNEL — UI-first [BLOCKING before any case block is written].**210211The reader is a **normal user / QC driving the running app** — no terminal, API client, database console, or log tail. Classify every mapped case into exactly ONE channel; the channel determines placement.212213**FIRST resolve the PROJECT's primary demo surface — one rung, stated once, before classifying cases.** Discover whether a front-end exists; record the landing rung and repeat it verbatim in the guide header.214215| Rung | Resolve when | What it changes below |216| ---- | ------------ | --------------------- |217| **Front-end present** | a discriminating signal resolves to a real user-facing app | Default — everything below applies exactly as written. |218| **`No front-end in this project — primary demo surface is {API / CLI / library / background job}`** | no signal resolves | That surface REPLACES the front-end throughout — **including the channel table below**: read "front-end" as that surface and "non-UI" as "not that surface", so its cases are the main-body channel, ordered first, and the appendix holds only what is not demoable on that surface either. The main-channel marker stays `🖥️`, but the WORD `UI` is replaced by the surface name everywhere the split is written. |219220**Discriminating signals** (`docs/project-config.json`): `modules[*].kind` (front-end/app/web vs library/service) · `e2eTesting.framework` (`"none"` means no browser surface) · `styling.guideDoc` · `designSystem.appMappings`. **NEVER test `framework.frontendPatternsDoc`**: it is a scaffold default and proves nothing. Whichever signal decides, state the rung; NEVER switch silently — why: without it, backend, CLI, library, and API products get an empty main body, an all-appendix guide, and a false thin-surface finding.221222| Channel | Test (first failure decides) | Placement |223| ------- | ---------------------------- | --------- |224| **🖥️ UI case** — *the demo* | Staged **and** observed entirely through the product's front-end: screens, forms, clicks, navigation, visible output | Main body, inside its story group, ordered first |225| **🔧 Technical case** | ANY step or expected result needs a non-UI surface — HTTP/API client, CLI, script, manual job/queue trigger, DB query, log or file inspection, config edit | Closing `## Appendix — Technical demo (non-UI)` — after every story, before the transparency note |226227- **UI cases carry the demo; technical cases are the appendix.** Order each story's cases UI-first, and NEVER let a technical case open a story, head the quick-reference table, or count as a main case to test. — why: the room believes what it watches happen in the app.228- **Hybrid = UI case.** A case demoed on screen whose data can ALSO be confirmed in the DB or logs stays a UI case — put that confirmation on its own **`Deeper confirmation (optional, non-UI)`** line, NEVER as a numbered demo step and NEVER on the proof chain. — why: every numbered step must be runnable by the presenter on screen with no tooling the audience has; and the proof chain is typed as `file:line` links a challenger can walk, so a runtime action ("query `orders` after clicking Save") on that line is an entry the auditor cannot open.229- **A story whose ONLY demonstration is technical is a stated finding.** Record `no UI demo path — technical only` in the story header and route its cases to the appendix. NEVER invent a screen, button, or admin page to make a case look UI-demoable. **Silent under the no-front-end rung** — a project with no front-end by design has no missing UI path to report; there the finding fires only when a case is not demoable on the project's primary surface either. — why: an invented surface fails live, and the audience discovers it before you do.230- **Announce the split in the guide header** — `Cases: 11 🖥️ UI · 3 🔧 technical (appendix)`. **Under the no-front-end rung** the split counts the primary surface as the main channel, and a large appendix is NOT a thin-surface finding — the stated rung already explains it. — why: for a product that HAS a front-end, a guide that is mostly appendix is telling the team the feature's user-visible surface is thin — a finding worth surfacing, not a formatting detail.231- **A technical case keeps the FULL four-part block and its proof rung** — it is demoted in ORDER and PROMINENCE, never in rigour. It obeys **every** per-case rule below: the four parts, real-user-path setup with no faked state, the `file:line` storage claim, the proof rung and chain; only its **observation** surface may be non-UI. — why: the appendix is a placement, not a lower evidence bar — and "not a main case" must never be read as "not bound by the per-case rules".232233## Step 4 — Trace Domain Storage & Solution (the distinctive step)234235For **each case** — UI and 🔧 technical — read the owning code and answer both questions with `file:line` evidence:236237- **How is domain data stored or changed?** Identify persisted field(s)/column(s)/table, owning value object/entity, migration, anchored/computed value, and additive/nullable/backfilled status. Read entity, DTO mapping, and migration — NEVER infer persistence from names.238- **How does the domain solve the feature?** Identify the rule/method/invariant consuming that data to produce the outcome (resolver/derivation/gate), and why storage makes it correct — including edge cases, legacy fallback, and cross-tier parity.239240For a display-only case, state **explicitly** that persistence does not change and describe the **representation** (computed value/shape and why correct). *"No storage change"* is valid; an empty block is not.241242## Step 5 — Open the Guide + Ledger, Accumulate Story by Story243244**Create the guide file BEFORE case one** and append as you produce it. NEVER hold the whole guide in context for one final write.245246**Write order is fixed:** title + a `<!-- task:START -->` / `<!-- task:END -->` placeholder marked `pending` (filled in Step 7) → header — scope/source, sources, delegations, tier/group count, **group ledger** rows `pending`, and empty `Appendix — Technical demo (non-UI)` heading → each group (trace → write main cases → **append 🔧 technical cases to the appendix** → mark its ledger row `written` with `main / technical` split → complete its todo) → guide-level sections (storage summary, quick-reference table, transparency note) **from written blocks** → chat summary. NEVER hold more than the current group; read finished blocks from disk — why: the appendix is last in the document but technical cases are written per group, preventing context loss.247248**After a cutoff, compaction, or resume:** the current task list → read the ledger → **verify every `written` row against the filesystem** — a group's cases live in **TWO** places, so check BOTH: the file exists AND carries that group's main-channel cases AND its 🔧 technical cases in the appendix; an absent or truncated block in **either** location resets the row to `pending` → re-read the contract and the Understanding Brief → continue at the first unfinished group. NEVER restart a finished group and never re-derive a written block from memory.249250> **[NO SILENT TRUNCATION]** If any cap, budget, or interruption leaves part of the resolved scope uncovered, name what was deferred or dropped **in the guide header AND in the chat summary** — *"Story D (bulk import, 9 cases) deferred — not covered by this guide."* — why: bounded coverage that reads as complete coverage sends a presenter into a room unprepared for the question nobody examined.251252**Write location — the demo guide is a DELIVERABLE, not a working artifact.** Write it to the project's demo-guide dir (Configuration); it is shared and version-controlled. **This deliberately differs from `$understand`, whose report is git-ignored** — do NOT copy that rule here — why: a guide the team cannot find is unused.253254## Step 6 — Write Each Case (four mandatory parts)255256Follow `references/demo-guide-template.md`. Per **case** — UI and 🔧 technical — the guide MUST contain:2572581. **Setup / preconditions** — exact state (roles, configuration, seed data, app/screen), staged through **real user paths**; never fake unreachable state. Secrets use `<redacted:…>`, accounts use roles.2592. **Step-by-step demo flow** — numbered, concrete click/action steps: actor, screen, input, and observation. **Every 🖥️ UI step runs in the front-end**; endpoint, command, query, or log inspection appears ONLY in a 🔧 technical appendix case. An untraceable step is a **stated blocker**, never an invented click.2603. **Expected result** — observable **discriminator**: the value that would have been WRONG under old behaviour, not generic "it succeeds".2614. **How the domain stores/changes data + solves it** — Step 4 in plain team language with `file:line` anchors.262263**Order inside every story: 🖥️ UI cases first** (happy path → variants → edge cases → legacy). 🔧 Technical cases are NOT inline; put them in the closing `Appendix — Technical demo (non-UI)` with the same four-part shape, after the last story — why: presenters read top-down.264265Also include: scope/source header with `{n} UI · {n} technical` split, story groups, **main case quick-reference table** (canonical identity · actual carrier reference(s) · what it proves · proof rung — main-channel cases only), **domain storage summary** per story, closing **technical demo appendix**, and **test-execution transparency note**. Keep prose tight.266267`--lang` given → emit a translated copy (prose translated; code identifiers, `file:line`, configured canonical IDs, executor references, and numeric values kept verbatim). `--html` given → follow the Artifact flow to render a self-contained runbook **after** the markdown is approved.268269## Step 7 — Compose the Task Block (top of the guide)270271**Purpose:** a developer/PO copies this block straight into the work tracker (Jira/ADO/Linear) without re-typing anything. It sits **above** the demo-guide body, immediately under the document title, fenced by `<!-- task:START -->` / `<!-- task:END -->` so it can be selected and copied in one go.272273**[BLOCKING] SOURCE IT, NEVER INVENT IT.** Fill every field from evidence already gathered in Steps 1–6:2742751. **A governing task / spec / story exists** (the business spec root — default `docs/specs/**`; a `specRoots.business.path` entry in `docs/project-config.json` overrides the path — a task or story artifact, a tracker item found in Step 2) → **copy its wording** for requirements, stories, and acceptance criteria; normalize formatting only. Cite the source path in the block header.2762. **No such artifact** → derive from the traced cases and code, and label the block `derived from code + demo cases this session — not yet reviewed by the PO`.2773. **A field has no evidence** → write the explicit negative (`None — no authorization behaviour in this item`), NEVER a plausible filler. An invented acceptance criterion is worse than an absent one: it enters the tracker as a commitment nobody agreed to.278279**Mandatory fields (all present; an inapplicable one states why):**280281| Field | Content | Sourced from |282| --- | --- | --- |283| **Title + type** | One-line item title · `Feature \| Enhancement \| Bug \| Tech` | Resolved scope (Step 0.1) |284| **Purpose / business value** | Why the item exists, for whom, and the outcome it buys — 2–4 sentences, no implementation detail | Spec/task, or Step 1 bar Q1 (before → after) |285| **Overall requirements** | What the item must deliver, as a short numbered list, plus explicit **In s286287…(truncated)