Agentic skill for feature demo

.agents/skills/feature-demo/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: feature-demo
+description: >-
+  Build a runnable, interactive single-page app that visualizes a newly-developed feature for a
+  community audience, starting from a git branch or PR. Produces a technical walkthrough
+  (architecture graph + live simulator) or a non-technical walkthrough (narrated slides) — both
+  with parameter controls that show how knobs affect each component of the system. Use when the
+  user wants to demo, showcase, explain, or visualize a branch / PR / feature for the community,
+  or asks to "make a demo of the code" / "сделать демо по коду".
+---
+
+# Feature Demo
+
+Turn a branch or PR into an interactive single-page app the community can open, run, and play
+with: change parameters, watch which components of the system react.
+
+## When to run
+
+The user points at a branch or PR — "make a demo for branch X", "explain PR #1234 to the
+community". Two output styles, both interactive SPAs:
+
+- **Technical** — architecture walkthrough for engineers: component graph, live simulator, code
+  references, failure modes. Spec: [references/technical-mode.md](references/technical-mode.md).
+- **Non-technical** — narrated slide walkthrough for the community: one idea per slide, plain
+  language, one interactive widget per slide. Spec: [references/nontechnical-mode.md](references/nontechnical-mode.md).
+
+If the user did not say which, ask: technical, non-technical, or both. Both → one app folder
+per mode.
+
+## Workflow
+
+1. **Resolve the input.** A branch name or a PR. Get the diff and full context — see
+   [references/analyze-feature.md](references/analyze-feature.md): `gh pr view` + `gh pr diff`,
+   or `git fetch && git diff <base>...<branch>`. Read the changed files, tests, migrations and
+   wiring until you understand the feature end to end.
+2. **Write the feature model.** Produce `feature-model.md` — the structured spec both renderers
+   consume: components, flows, parameters, the parameter→effect mapping, lifecycle/states,
+   failure modes, narrative beats. Schema in [references/analyze-feature.md](references/analyze-feature.md).
+   Do not skip this; it is what keeps the demo accurate.
+3. **Confirm with the user.** Show the feature-model summary and the chosen mode(s) before
+   building. Fix misunderstandings now, not in the SPA.
+4. **Scaffold the SPA.** One Vite + React + TS + Tailwind app per mode, **always created
+   inside `tmp/`** — exact commands in [references/scaffold.md](references/scaffold.md).
+5. **Build the content** from the feature model, following the chosen mode spec. Non-negotiable:
+   real parameter controls bound to the feature's actual knobs, and a visualization that reacts.
+6. **Verify and hand off.** Run `npm run build` — it must compile clean. Write a `README.md` in
+   the output folder with the single run command. Tell the user the folder and the command.
+
+## Core principle
+
+Every demo answers one question visually: **change a parameter → see which components of the
+system change, and how.** A demo with no working controls, or controls that do not visibly move
+the system, is not done. The feature model's parameter→effect mapping is the contract for this;
+keep that logic in pure functions (`model/effects.ts`) shared by both modes.
+
+## Output
+
+Always scaffold into `tmp/feature-demo/<branch-slug>/` (one subfolder per mode) — never anywhere
+else in the repo. `tmp/` is git-ignored, so the generated project (and its large `node_modules`)
+can never be committed by accident. If `tmp/` does not exist yet, create it. The user runs the
+app with one command (`npm run dev`). Never auto-deploy.

.agents/skills/feature-demo/references/analyze-feature.md

@@ -0,0 +1,81 @@
+# Analyzing a feature into a feature model
+
+The feature model is the single source of truth for both demo modes. Spend real effort here —
+an inaccurate model produces a confident, wrong demo.
+
+## 1. Gather context
+
+Resolve the input to a base branch and a feature branch:
+
+- **PR:** `gh pr view <n> --json title,body,headRefName,baseRefName,files,commits` then
+  `gh pr diff <n>`.
+- **Branch:** `git fetch origin <branch> <base>` then `git diff origin/<base>...origin/<branch>`
+  (base is usually `main`; for this repo a PR may target `devnet-ready` or `testnet` — use the
+  PR's actual `baseRefName`).
+
+Then read — do not skim:
+
+- Every changed source file; new modules first.
+- Tests — they show intended behavior and the edge cases the author cared about.
+- Migrations — they show storage / on-chain state changes.
+- Benchmarks, runtime/config wiring, `Cargo.toml` — they show how the feature is hooked in.
+- The PR description and any linked issues for intent and rationale.
+
+If behavior is ambiguous, ask the user. Never invent behavior to fill a gap.
+
+## 2. Write `feature-model.md`
+
+Save it in the output folder. Sections:
+
+### Header
+- `feature` — short name.
+- `summary` — one sentence, plain language.
+- `problem` — what was wrong or missing before this feature.
+- `branch` / `pr` — identifiers, base branch.
+
+### Components
+The parts of the system the feature involves. These become nodes in the technical graph and
+actors in the non-technical narrative. For each: `id`, `name`, `role` (one line),
+`kind` (existing | new | modified), `source` (file path, `file:line` where useful).
+
+### Flows
+Directed relationships between components — data flow, control flow, handoffs, hooks. For each:
+`from`, `to`, `label`, `when` (the trigger or condition).
+
+### Parameters — the heart of the demo
+The tunable knobs the feature introduces or changes. For each:
+- `id`, `name`.
+- `type` — range | enum | boolean.
+- `default`, plus `min` / `max` / `step` or `options`, and `unit`.
+- `maps_to` — the code symbol it corresponds to (storage item, config constant, extrinsic arg).
+- `realistic` — a realistic value or scenario for the default view.
+
+### Parameter → effect mapping — what the visualization shows
+For each parameter, the concrete cause→effect chain: which components change, which values
+recompute, and the formula or rule. Be concrete enough to implement in JavaScript. Example:
+
+> `tempo` ↑ → epoch period (`tempo + 1`) ↑ → fewer epochs per day → `next_epoch_block`
+> shifts later → coinbase emission cadence slows.
+
+Pull the real formulas from the code. This mapping must be **executable** — it becomes
+`model/effects.ts`.
+
+### Lifecycle / states
+If the feature has a state machine or staged process: the states, the transitions, and what
+triggers each. Many features have one (a referendum lifecycle, a request lifecycle, an epoch).
+
+### Failure modes
+How the feature breaks if misconfigured or misused — out-of-range parameters, missing guards,
+ordering bugs, panics at boot. The technical demo surfaces these explicitly.
+
+### Narrative beats
+For the non-technical mode: an ordered list of 6–12 beats, each one idea, building from "why"
+through "how" to "what it means". Each beat maps to one slide.
+
+## 3. Sanity-check the model
+
+- Every parameter has an effect mapping with a real formula or rule — not a vague description.
+- Every component appears in at least one flow.
+- `summary` and `problem` are understandable by a non-engineer.
+- Every number (default, bound) comes from the code, not a guess.
+- You could hand `feature-model.md` to a stranger and they could rebuild the demo from it.

.agents/skills/feature-demo/references/nontechnical-mode.md

@@ -0,0 +1,53 @@
+# Non-technical mode — narrated walkthrough
+
+Audience: the community — token holders, users, non-engineers. Goal: they understand what
+changed, why it matters to them, and feel the mechanic by touching it once.
+
+Reference example: the Subtensor *governance walkthrough* — a hash-routed slide deck, one idea
+per slide, plain language, a friendly semantic palette, smooth transitions, and one interactive
+widget per mechanic slide.
+
+## Layout
+
+A slide deck. One concept per slide. Hash-routed (`#1`, `#2`, …) so any slide is linkable.
+Prev / next buttons, arrow-key navigation, and a progress indicator (slide N of M).
+
+Slides come from the model's narrative beats. Typical arc:
+
+- **Title** — the feature, one line.
+- **Why** — the problem, in human terms.
+- **The core idea** — one sentence.
+- **3–6 mechanic slides** — one piece each, every one carrying an interactive widget.
+- **Trade-offs** — what was chosen, and what was given up.
+- **Safety / limits** — what stops it from going wrong.
+- **Closing** — what it means for the community.
+
+## Visual style
+
+- Sans-serif, generous spacing, large readable type. No code, no jargon — or define a term
+  inline, once, the first time it appears.
+- Friendly semantic colors: green = good / approve, red = stop / reject, amber = caution,
+  blue = neutral / info.
+- Smooth slide transitions with `motion` (Framer Motion).
+
+## Required interactive pieces
+
+1. **One widget per mechanic slide** — a slider, toggle, or small simulation tied to a real
+   parameter from the model.
+2. **A visible consequence.** Moving the widget changes something the viewer can see: a number,
+   a chart (`recharts`), an animation, a component lighting up. Use the *same*
+   `model/effects.ts` functions as the technical mode, so both demos agree on the numbers.
+3. **Plain-language framing.** Each slide states its takeaway in one sentence before the widget;
+   the widget then proves that sentence.
+
+## Writing rules
+
+- No undefined jargon. Translate every code term into a human one (e.g. "epoch" → "scoring
+  round", "extrinsic" → "on-chain action").
+- One idea per slide. If a slide needs two paragraphs of explanation, it is two slides.
+- Lead with the consequence for the user, not the implementation detail.
+
+## Done when
+
+A non-engineer can click through every slide, touch each widget, and then explain back what the
+feature does and why it matters.

.agents/skills/feature-demo/references/scaffold.md

@@ -0,0 +1,90 @@
+# Scaffolding and running the SPA
+
+One Vite app per mode. Commands assume npm; pnpm or yarn work the same way.
+
+## Where to create it
+
+Always scaffold inside `tmp/` — `tmp/feature-demo/<branch-slug>/` (add a `-technical` /
+`-nontechnical` suffix when building both). `tmp/` is git-ignored, so a generated project can
+never be accidentally committed. Never scaffold anywhere else in the repo.
+
+## Create the project
+
+```sh
+mkdir -p tmp/feature-demo
+npm create vite@latest tmp/feature-demo/<branch-slug> -- --template react-ts
+cd tmp/feature-demo/<branch-slug>
+npm install
+```
+
+## Add Tailwind v4
+
+```sh
+npm install tailwindcss @tailwindcss/vite
+```
+
+In `vite.config.ts`, add the plugin:
+
+```ts
+import tailwindcss from '@tailwindcss/vite'
+// plugins: [react(), tailwindcss()]
+```
+
+Replace the contents of `src/index.css` with a single line:
+
+```css
+@import "tailwindcss";
+```
+
+## Add mode libraries
+
+- **Technical mode:** `npm install @xyflow/react lucide-react`
+- **Non-technical mode:** `npm install recharts motion lucide-react`
+  - `motion` is the current package for Framer Motion; import from `motion/react`.
+
+Install latest versions. If a library's current API differs from what a mode spec describes,
+check that library's docs and adapt — the spec describes intent, not exact signatures. Do not
+pin to old versions.
+
+## Project structure
+
+```
+src/
+  main.tsx
+  App.tsx              # layout shell — sidebar (technical) or slide router (non-technical)
+  feature-model.ts     # the feature model as typed, importable data
+  model/effects.ts     # pure functions: parameters -> derived system state
+  components/          # graph, controls, panels, slides, charts
+  index.css
+feature-model.md       # the human-readable model — keep this in the folder too
+README.md              # how to run
+```
+
+Encode the feature model into `feature-model.ts` as typed data (components, flows, parameters,
+effect metadata). Put every cause→effect calculation into pure functions in `model/effects.ts`:
+`(parameters) => derivedState`. The UI is a thin layer over these functions — both modes import
+the *same* `effects.ts`, so a technical and non-technical demo of the same feature never
+disagree.
+
+## Verify
+
+`npm run build` must pass with no TypeScript errors before you hand off. Fix every error; do not
+hand the user a project that does not compile.
+
+## README.md to write into the output folder
+
+State the single run command and what the demo is:
+
+```md
+# <Feature> — <technical|non-technical> demo
+
+Interactive walkthrough of <feature> (branch `<branch>` / PR #<n>).
+
+## Run
+
+    npm install && npm run dev
+
+Then open the printed `localhost` URL.
+```
+
+After `npm install` has been run once, the user's single command is `npm run dev`.

.agents/skills/feature-demo/references/technical-mode.md

@@ -0,0 +1,50 @@
+# Technical mode — architecture walkthrough
+
+Audience: engineers who will read the code. Goal: they understand the architecture, can reason
+about every parameter, and see how the feature fails when misconfigured.
+
+Reference example: the Subtensor *governance architecture walkthrough* — a sidebar-navigated
+single page with an interactive component graph, a live referendum simulator, an adjustment-curve
+chart, and explicit failure-mode callouts, all written in code-precise language.
+
+## Layout
+
+Single page. Left sidebar navigation, collapsible. One scrollable section per major area of the
+feature; clicking a sidebar entry jumps to its section.
+
+Typical sections — adapt to the feature:
+
+- **Architecture** — the component graph.
+- **Structure / composability** — how the parts connect; traits, interfaces, ownership.
+- **Configuration** — every parameter, what it does, its bounds and code symbol.
+- **Lifecycle** — the state machine, if the feature has one.
+- **Simulator** — the live, interactive core.
+- **Failure modes** — how misconfiguration breaks it.
+
+## Visual style
+
+- Dense, precise, monospace-forward. Mono font for code and identifiers
+  (`ui-monospace, "JetBrains Mono", "Fira Code", Consolas`); a sans-serif for prose.
+- Light background, restrained palette — greys plus one accent. No decorative gradients.
+- Show the real code symbols: type names, trait names, extrinsic names, `pallet/file.rs`
+  references. Engineers trust a demo that names the same things the code does.
+
+## Required interactive pieces
+
+1. **Component graph.** Use `@xyflow/react`. Nodes = components from the model, edges = flows.
+   Lay it out, make it pannable / zoomable / draggable. Clicking a node opens its details —
+   role, source file, the parameters that touch it.
+2. **Parameter panel.** Every parameter from the model as a real control: slider for `range`,
+   select for `enum`, switch for `boolean`. Label each with its `maps_to` code symbol and bounds.
+3. **Live effect.** Changing a parameter immediately recomputes derived state through the pure
+   functions in `model/effects.ts` and updates, in the same frame: highlighted nodes/edges in
+   the graph, a results panel listing the recomputed values, and any chart.
+4. **Simulator** — if the feature has a lifecycle. Let the user step or play through the state
+   machine, drive its inputs, and watch the current state, transitions, and side effects.
+5. **Failure-mode callouts.** For each failure mode, a preset or control that reproduces it,
+   plus a plain explanation of exactly what breaks and why.
+
+## Done when
+
+An engineer can open it, change every parameter, watch the exact components and values that
+depend on it react, and trace each effect back to a named code symbol.