prd-interactive-review

What this skill does

# PRD Interactive Review

## Purpose

Render a finished or near-final PRD (or comparable spec) as a self-contained, interactive HTML artifact whose single job is to make **vetting and approving** the document faster and more immersive than reading the source markdown. The deliverable exploits HTML's interactive nature — tabbed navigation, SVG flow diagrams with clickable detail, progressive disclosure, and color used as a signal — so a reviewer grasps the critical points and signs off with minimal effort.

This is **not** a markdown-to-HTML converter. A long scrolling page that merely adds color "misses the point of HTML." Optimize for comprehension-before-sign-off, not for reproducing every line.

## Core principles

1. **Purpose first.** The artifact exists to be inspected and approved. Be faithful to the source on critical points only — not 1:1. Keep the source `.md` canonical for complete text.
2. **Single file.** Inline all CSS and JS. No CDN or external assets. Must work offline and print cleanly.
3. **Tabbed SPA, never a scroll.** One focused idea per tab. Lead each tab with its strongest visual.
4. **Dynamise the dynamics.** Any process, lifecycle, or state machine becomes a real SVG flow diagram showing temporal/sequential order, including branches and loop-backs, with clickable nodes that reveal detail. Never explain a flow with side-by-side text columns.
5. **Per-variant diagrams.** Multiple scenarios (user stories, modes) each get their own switchable flow.
6. **Progressive disclosure.** Collapse fine detail (FRs, NFRs, fine print) into accordions; surface only IDs and a one-line gist by default.
7. **Color = signal, not decoration.** Emphasize what matters (gates, decisions, ordered phases); keep routine/native detail gray or omit it. If most of the page is colored, nothing stands out.
8. **Interactivity earns its place.** Every tab, accordion, and click-to-detail must reduce the reviewer's effort. If it does not, remove it.

## Workflow

To build the review experience, follow these steps in order.

### 1. Extract the critical points

Read the source PRD/spec. Identify what a reviewer must understand to approve: the problem and its evidence, the core method/model, the key mechanism (how it works), the distinct usage scenarios, the scope (in/out), and — most important — any **decisions that block sign-off** (look for "DECISION NEEDED", open questions, `[ASSUMPTION]` tags). Note anything that is a *process, lifecycle, or state machine*, since that becomes the centerpiece diagram.

### 2. Choose a tab structure that fits the document

Pick 4–6 tabs. A common, strong mapping is: **The Problem → The Method → The Mechanism → Usage Stories → Build Plan**. Rename to fit the document's vocabulary. The invariant: one focused idea per tab, strongest visual leads, fine print collapses. See `references/diagram-and-color-patterns.md` for the tab-structure rationale.

### 3. Start from the scaffold

Copy `assets/prd-review-scaffold.html` to the output location (next to the source file, e.g. `prd.html` in the same folder). It already contains the tab nav, view-switching JS, SVG arrowhead marker defs, the clickable-node detail-panel pattern, per-variant sub-tabs, accordion CSS, and the color-token system. Replace the `{{PLACEHOLDERS}}` and example views with extracted content. Do not rebuild this boilerplate from scratch.

### 4. Build the mechanism diagram (the centerpiece)

For the "how it works" tab, build an SVG flow/state machine showing the real temporal flow. Lay nodes top-to-bottom in execution order; draw connectors first; branch at gates with a green YES edge continuing down and a **dashed red loop-back** edge returning to an earlier node; pulse the gates; make every node clickable into the detail panel. Consult `references/diagram-and-color-patterns.md` for the exact construction recipe, loop-back path geometry, and marker usage.

### 5. Build per-variant flows

For each usage scenario, add a switchable variant. For mostly-linear scenarios a horizontal pipeline of chips reads fastest; highlight only the node that *differs* between variants and add a one-sentence "What's different" callout mapping to the relevant FR/decision. Reach for full SVG only when a variant has its own branching/loops.

### 6. Apply the color system

Use the scaffold tokens consistently: indigo `--accent` for the actor/governed unit, the `--hot → --warm → --cool` ramp for any ordered sequence (phases/severity/maturity), red `--block` strictly for gates and blocking decisions, green `--go` for pass/done, gray for routine. Default everything to gray and promote to color only where attention is earned. Always include the diagram legend.

### 7. Surface the decisions needing sign-off

On the Build-Plan tab, render the blocking decisions prominently (warn/block callouts) and collapse the full FR/NFR text into accordions showing IDs plus a one-line gist. The reviewer should be able to find "what do I need to decide?" in seconds.

### 8. Open it for review

Open the result in the browser (`open <path>` on macOS) so the user can inspect and approve. State clearly that the `.md` remains the canonical source and the HTML matches it on the critical points only.

### 9. Iterate on feedback

Expect the reviewer to push for clearer flow, less clutter, or stronger emphasis. Treat that as the normal loop: adjust diagrams, demote detail to gray/accordions, sharpen color usage, reopen.

## Bundled resources

- **`assets/prd-review-scaffold.html`** — the reusable single-file HTML scaffold (tab nav, view-switching JS, SVG marker defs, clickable detail panel, per-variant sub-tabs, accordion CSS, color tokens). Copy and fill it; do not recreate it.
- **`references/diagram-and-color-patterns.md`** — detailed techniques: the color-as-signal table, the SVG flow/state-machine construction recipe with loop-back geometry, per-variant flow patterns, tab-structure rationale, and what to leave out. Load when building diagrams or deciding the color system.