diff --git a/.agents/skills/feature-demo/SKILL.md b/.agents/skills/feature-demo/SKILL.md new file mode 100644 index 0000000000..0980198517 --- /dev/null +++ b/.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 ...`. 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//` (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. diff --git a/.agents/skills/feature-demo/references/analyze-feature.md b/.agents/skills/feature-demo/references/analyze-feature.md new file mode 100644 index 0000000000..c05ed97320 --- /dev/null +++ b/.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 --json title,body,headRefName,baseRefName,files,commits` then + `gh pr diff `. +- **Branch:** `git fetch origin ` then `git diff origin/...origin/` + (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. diff --git a/.agents/skills/feature-demo/references/nontechnical-mode.md b/.agents/skills/feature-demo/references/nontechnical-mode.md new file mode 100644 index 0000000000..f44ada804d --- /dev/null +++ b/.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. diff --git a/.agents/skills/feature-demo/references/scaffold.md b/.agents/skills/feature-demo/references/scaffold.md new file mode 100644 index 0000000000..97bdefd6d1 --- /dev/null +++ b/.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//` (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/ -- --template react-ts +cd tmp/feature-demo/ +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 +# demo + +Interactive walkthrough of (branch `` / PR #). + +## 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`. diff --git a/.agents/skills/feature-demo/references/technical-mode.md b/.agents/skills/feature-demo/references/technical-mode.md new file mode 100644 index 0000000000..66bef4450f --- /dev/null +++ b/.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. diff --git a/.claude/skills/feature-demo/SKILL.md b/.claude/skills/feature-demo/SKILL.md new file mode 100644 index 0000000000..0980198517 --- /dev/null +++ b/.claude/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 ...`. 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//` (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. diff --git a/.claude/skills/feature-demo/references/analyze-feature.md b/.claude/skills/feature-demo/references/analyze-feature.md new file mode 100644 index 0000000000..c05ed97320 --- /dev/null +++ b/.claude/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 --json title,body,headRefName,baseRefName,files,commits` then + `gh pr diff `. +- **Branch:** `git fetch origin ` then `git diff origin/...origin/` + (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. diff --git a/.claude/skills/feature-demo/references/nontechnical-mode.md b/.claude/skills/feature-demo/references/nontechnical-mode.md new file mode 100644 index 0000000000..f44ada804d --- /dev/null +++ b/.claude/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. diff --git a/.claude/skills/feature-demo/references/scaffold.md b/.claude/skills/feature-demo/references/scaffold.md new file mode 100644 index 0000000000..97bdefd6d1 --- /dev/null +++ b/.claude/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//` (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/ -- --template react-ts +cd tmp/feature-demo/ +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 +# demo + +Interactive walkthrough of (branch `` / PR #). + +## 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`. diff --git a/.claude/skills/feature-demo/references/technical-mode.md b/.claude/skills/feature-demo/references/technical-mode.md new file mode 100644 index 0000000000..66bef4450f --- /dev/null +++ b/.claude/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.