skillpacks 0.1.1 → 0.1.2

package/packs/product-design/claude/spec-interview/archive/v0.13/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: spec-interview
+description: Post-prototype production deep dive — walks through consolidated prototype screen by screen to extract production specifications
+type: planning
+version: v0.13
+argument-hint: "[optional-topic-override] [--ideas]"
+context_intake: deep
+---
+
+## Pack Availability Guard
+
+Before telling the user to run a skill from another project-local pack, check `.agents/project.json.enabled_packs`. If the target pack is not enabled, recommend `npx skillpacks install <pack>` from the project shell, instead of the target skill. Global skills are always valid. Skills from this same pack are valid because the current skill is already running from that pack.
+
+## Prototype Gate
+
+Before starting the interview process, verify:
+
+1. A consolidated prototype exists at `prototypes/{topic}/consolidated/`. If missing, halt and recommend `/consolidate-variations` first.
+2. All research tasks from the `--post-prototype` pass are completed — check `tasks/todo.md` for unchecked items under `## Priority Documentation Todo` that reference post-prototype research. If unchecked post-prototype items remain, halt and recommend completing those first.
+
+If both gates pass, proceed with the interview.
+
+# Spec Interview
+
+Interview the user to validate, refine, and complete an implementation specification from a consolidated prototype and research context. For half-formed product ideas, run `/idea-scope-brief` before this skill.
+
+## Process
+
+### 0. Product-Path Scope Resolution
+
+Resolve research scope by product path before using code or app structure as a hint:
+
+1. If `$ARGUMENTS` names a non-archived `research/{slug}/` directory or a product-path ID whose `scope_path` points there, use that path. Treat `{slug}` as the product/app name, not the ICP, audience, or segment label.
+2. If `$ARGUMENTS` names only `research/_archive/{slug}/` or a manifest entry with `status: archived` or legacy `status: abandoned`, stop and warn that the path is archived; do not write or update scoped outputs there.
+3. Read `research/.progress.yaml` when present. Normalize legacy `active_path` to `active_paths` on read and write back `active_paths` on manifest updates. Treat legacy `abandoned` as `archived`; exclude `archived`, `abandoned`, `deferred`, `revisit_candidate`, `promoted`, and any `scope_path` under `research/_archive/` from active target selection.
+4. If active product paths exist in the manifest, use those paths. If multiple active paths exist, ask which one to target unless this skill explicitly supports cross-path output.
+5. If no active manifest target exists, list non-archived product directories under `research/`, excluding `research/_archive/` and dot directories. Auto-select only when exactly one exists; ask when multiple exist.
+6. If no product directories exist, use flat `research/` single-product mode.
+7. Detect monorepo/app/package structure only as a secondary hint. Suggest creating a missing `research/{slug}/` product path when code clearly exposes an app, but do not require code or monorepo detection before using `research/{slug}/`.
+
+When product path `{slug}` is active, read and write research under `research/{slug}/`, specs under `specs/{slug}/`, and treat top-level `research/*.md` files as flat-mode documents or cross-path summaries.
+
+1. **Read consolidated prototype and research context:**
+   - Read the consolidated prototype directory at `prototypes/{topic}/consolidated/` as the primary input. Walk through every screen, component, and interaction in the prototype to understand the current state.
+   - If `.agents/project.json` exists, read `project_type` and `enabled_packs` before choosing a research frame.
+   - For `business-app`, read `research/icp.md` when present and ground solution decisions against the ICP.
+   - For `game`, read game research artifacts when present: `research/game-audience.md`, `research/game-fantasy.md`, `research/game-core-loop.md`.
+   - For `devtool`, read devtool research artifacts when present: `research/devtool-user-map.md`, `research/devtool-dx-journey.md`, `research/devtool-integration-map.md`.
+   - If project type is missing or mismatched, recommend `/pack recommend`, `npx skillpacks install <pack>` from the project shell before doing domain-specific planning.
+   - If `research/idea-brief.md`, `research/icp.md`, or `research/journey-map.md` exists in a business-app project, treat them as source evidence: does this implementation fit the concept constraints, user and customer journey, path to aha, conversion path, retention loop, champion dynamics, technical sophistication, and provisioning/onboarding model?
+   - If lifecycle evidence is missing and the `customer-lifecycle` pack is not enabled, recommend `npx skillpacks install customer-lifecycle` from the project shell, before `/journey-map`.
+   - When the user proposes something that conflicts with the ICP or journey map, flag it — e.g., "The journey map says the buyer needs a demo before sign-up — does this self-serve-only onboarding fit?"
+   - Do not re-interview on concept, ICP, or journey topics already covered — focus on technical solution design.
+   - Read `specs/user-flow-*.md` when present as upstream evidence for screen order, route inventory, branch decisions, state coverage, failure/recovery paths, handoffs, and low-fidelity wireframe intent.
+
+2. **Surface a prototype-grounded assumptions checkpoint before probing:**
+   - After reading the consolidated prototype and research context but **before** asking deep probing questions, present a concise **Assumptions Checkpoint** grounded in what the prototype reveals.
+   - Tag each assumption with its source:
+     - `[from spec]` — explicitly stated in the draft or spec document
+     - `[from codebase]` — derived from reading existing code, config, or infrastructure
+     - `[from research]` — derived from research docs (ICP, audience, journey maps)
+     - `[from prototype]` — derived from the consolidated prototype
+     - `[inferred]` — not stated anywhere; you filled in a default or made a judgment call
+   - Keep the checkpoint short enough to preserve interview momentum: normally 3 to 7 bullets, grouped only when useful. Do not dump a comprehensive manifest unless the user explicitly asks to review assumptions first.
+   - Bias the checkpoint toward assumptions that are uncertain, risky, contradicted by evidence, or likely to change data/API/architecture choices. Omit obvious restatements that can be captured later in the spec.
+   - Focus the checkpoint on what the prototype assumes vs what production needs:
+     - What the prototype assumes about **data model** — what's fake/fixture vs what needs real persistence
+     - What the prototype assumes about **auth** — none? mock? real?
+     - What **fake data needs to become real** — hardcoded lists, mock APIs, placeholder content
+     - What **missing infrastructure** is needed — database, auth, payments, analytics, deployment
+     - What **error/empty states** the prototype skips vs what production needs
+   - Deliver the checkpoint inline as the final message text of its own turn — never only as mid-turn text in a turn that ends with a tool call. In the next turn, use AskUserQuestion to ask the user to confirm or correct it and include the first 1 to 3 focused interview questions so momentum is kept. Option previews may mirror the checkpoint as a supplement but are never the sole channel. Do not stop at the assumptions checkpoint unless the user explicitly asks to pause and review assumptions first.
+   - If any `[inferred]` assumption is corrected, note the correction — these corrections are high-signal for downstream risk and must appear in the interview log.
+
+3. **Screen-by-screen prototype walkthrough:**
+   - Walk through each screen/page in the consolidated prototype. For each screen, use AskUserQuestion to probe:
+     - **Data model?** What entities, relationships, persistence does this screen need?
+     - **API calls?** What endpoints, payloads, error responses?
+     - **Auth?** What permissions, roles, access control apply to this screen?
+     - **Empty/error states?** What happens when data is missing, requests fail, or the user has no content yet?
+     - **Performance?** Loading states, pagination, caching needs?
+     - **Analytics?** What events should be tracked on this screen?
+   - Ask one to three focused questions per turn.
+   - **Research and recommend by default.** For each decision point, use web search, upstream research docs (`research/*.md`), and codebase analysis to gather evidence before asking the user. Present your findings with data, state your recommendation with reasoning, and ask the user to approve, adjust, or override. When a decision point genuinely has multiple viable approaches, list each option with a clear rationale, pros/cons, and your recommendation with reasoning. For the recommended option, explain how the con can be mitigated if feasible. Only ask the user to choose without a recommendation when the decision genuinely requires insider knowledge (internal constraints, personal preferences, strategic bets). Do not manufacture choices.
+
+4. **Iterative prototype updates:**
+   - When the interview reveals gaps in the prototype (missing screens, unclear flows, absent states), use AskUserQuestion: "Should I update the prototype to add [gap]? This may warrant re-running upstream steps."
+   - If the consolidated prototype exposes missing or unclear screen flow, branch coverage, state coverage, failure/recovery behavior, or handoff structure, recommend `/user-flow-map [topic]` as the upstream remediation before continuing production-spec work.
+   - The user decides per-update whether to update the prototype now or note it for production implementation only.
+   - If the user approves a prototype update, make the change and note it in the interview log before continuing.
+
+5. **Cover all areas:**
+   - Continue until you have thoroughly covered: implementation goals, technical architecture, data models, APIs/contracts, migrations, edge cases, security, performance, observability, test strategy, and scope boundaries.
+   - **Coverage checkpoint** — Before concluding, present a structured summary inline as the final message text of its own turn: list each area covered with the key decisions made and the evidence or reasoning that supported each decision. In the next turn, use AskUserQuestion to ask: "Does this cover everything? Any areas we should revisit or that I missed?"
+
+6. **Write outputs:**
+   - Write the completed specification to `specs/[topic].md` (create the `specs/` directory if it doesn't exist) where `topic` is a short kebab-case summary.
+   - The spec must use these canonical section headings (unnumbered):
+     - `## Overview`
+     - `## Goals`
+     - `## Non-Goals`
+     - `## Detailed Design` (architecture, data models, APIs, UI flows)
+     - `## Edge Cases`
+     - `## Test Plan`
+     - `## Acceptance Criteria`
+     - `## Open Questions`
+     - `## Assumptions & Risks` (the checkpoint output)
+     Additional topic-specific sections (e.g. `## Data Model`, `## Security`) may appear between Detailed Design and Edge Cases. Do not number sections.
+   - Append an **Assumptions & Risks** section to the end of the spec listing: each checkpoint assumption that was confirmed, corrected, or left unresolved during the interview, its source tag, and the downstream risk if the assumption turns out to be wrong later. Flag any `[inferred]` assumptions that were never explicitly confirmed by the user.
+   - Create an interview log file named `[topic]-interview.md` recording each turn of the interview including questions asked, options presented with pros/cons, and user selections. The log must include the Assumptions Checkpoint as presented, user corrections, and a summary of significant deviations from the original spec.
+
+## Output
+
+Two files written:
+
+- `specs/[topic].md` — the completed specification
+- `[topic]-interview.md` — full interview log with deviation summary
+
+### Alignment Page
+
+When this skill produces durable deliverables (research, specs, plans, reports, prototypes, or any document output), build a full-depth HTML alignment page following `ALIGNMENT-PAGE.md` in this skill's directory. Output: `alignment/spec-interview-{topic}.html`.
+
+## Constraints
+
+- Use AskUserQuestion for all interview turns — do not assume answers.
+- One to three focused questions per turn, not more.
+- Do not re-interview on ICP topics already covered in `research/icp.md`.
+- Do not conclude the interview without explicit user confirmation that all areas are addressed.
+- When recommending a skill from another pack, verify the pack is installed via `.agents/project.json` `enabled_packs`. If not installed, recommend `npx skillpacks install <pack-name>` from the project shell, before the target skill.
+
+## Ideas Mode (`--ideas`)
+
+When `$ARGUMENTS` contains `--ideas`, read `tasks/ideas.md` and run the interview process for each idea sequentially.
+
+### Process
+
+1. Read `tasks/ideas.md` and extract every distinct idea entry. If `$ARGUMENTS` includes a filter keyword (beyond `--ideas`), limit to matching ideas.
+2. Show the user the list and ask them to confirm, skip any, or reorder.
+3. For each idea, run the standard interview process using the idea's title and description as the initial implementation draft. If an idea is still only a raw concept, route it to `/idea-scope-brief` first.
+4. Write deliverables (`specs/[topic].md` and `[topic]-interview.md`) for each completed idea.
+5. After each idea, summarize decisions and move to the next. The user may say "skip" to move on.
+
+If the user stops partway through, write deliverables for completed ideas and note which remain.
+
+## Archive-First Replacement Policy
+
+- Before replacing or substantively rewriting an existing canonical research/spec document (`research/**/*.md`, `specs/**/*.md`, or `docs/specifications/**/*.md`), copy the current file to `docs/history/archive/YYYY-MM-DD/HHMMSS/<original-relative-path>`.
+- Preserve the archived snapshot exactly as it existed before the change; do not edit the archived copy after creating it.
+- After the archive snapshot exists, write the updated document to the original canonical path.
+- Report both the archive path and the updated canonical path in the final output.
+- New files do not need archive snapshots. Append-only updates do not need archive snapshots unless an existing section is regenerated or rewritten.
+- Keep any existing user approval requirement before overwriting or replacing a document; archiving does not replace asking when the skill already requires approval.
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.

package/packs/product-design/claude/ui-interview/ALIGNMENT-PAGE.md

@@ -9,6 +9,8 @@ When this skill produces durable deliverables (research, specs, plans, reports,
 
 The tier is set per skill via `visual_tier` in SKILL.md frontmatter (or detected by the upgrade script). The bundled ALIGNMENT-PAGE.md receives tier-appropriate rendering guidance from the generator.
 
+**Context intake.** This skill declares `context_intake: deep` (Deep interview). Gather repo/project context before asking, present an assumptions manifest when the contract requires it, ask focused questions, and confirm coverage before building review artifacts.
+
 **Alignment lifecycle.** Alignment pages have three lifecycle states. `review` is the draft/pre-approval page: it contains the complete deliverable preview, evidence, required inline gate questions, section feedback controls, local section-feedback YAML only after a section feedback choice is selected, and one bottom `Compile Responses` control. `confirmed` is the post-approval page after the agent has consumed final compiled response YAML, made any approved user-requested edits, and written or updated the approved canonical artifacts. A confirmed page is finished and current for the completed alignment cycle, but it remains amendable when later research changes or extends the conclusions. `amended` is a future revision of a confirmed page: archive the previous confirmed page first, mark what changed, preserve the prior approval record, and highlight the new evidence, decisions, or scope that changed the earlier conclusion.
 
 **Central alignment index.** When a research-producing skill writes or updates an HTML alignment page, also maintain the repository's central alignment index. Look for `alignment/index.html` at the repository root; if the target repo documents a different central alignment-index path, use that path and report it. If the index does not exist, create it as a self-contained HTML page that works from `file://`, links to every active `alignment/*.html` page except itself, and includes the newly written page. Every index entry must include the page's alignment date in a muted meta span after the link, formatted `YYYY-MM-DD`, for example `<a href="page.html">Title</a> <span class="meta">2026-06-09</span>`. The alignment date is the review or confirmed date written inside the page itself; new pages use today's date. If the index exists, update it instead of blindly appending: preserve valid existing entries, metadata, and entry dates; remove duplicate entries for the same page path; keep links repo-relative; and include the new or updated page. When updating an existing index, add a date only to entries that are missing one, deriving it from the page's internal alignment date, or from file history when the page has no internal date. If a `new` marker is used, combine it with the date as `<span class="meta">new · YYYY-MM-DD</span>`, and remove stale `new` markers from entries that are no longer the latest addition.
@@ -57,9 +59,11 @@ The tier is set per skill via `visual_tier` in SKILL.md frontmatter (or detected
 
 **Report-only research gates.** For report-only or pre-approval research skills, the first `review` alignment page must explicitly contain proposed research scope, source plan, assumptions/confidence, recommended output path, proposed file changes, and approval gates before synthesized research begins and before any working packet, canonical research, spec, or task file is created or updated.
 
-**Staged research workflow.** Heavy report-first research uses a scope-first three-stage approval workflow. Stage 1 is minimal scope discovery only: inspect enough repository, user, and source context to propose research scope, source plan, assumptions, output paths, and approval questions. Build the `review` alignment page before synthesized research. The page must render the proposed scope, available source categories, known context, assumptions/confidence, proposed working-packet and canonical output paths, and research-scope approval gates. Stop for final compiled response YAML approval of the research scope. Do not synthesize findings, rank candidates, recommend a path, or create working packets, canonical research, spec, or task files in Stage 1. Stage 2 starts only after final compiled response YAML approves the research scope with no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Perform the synthesized research, run required source/code checks, and write only a non-canonical working packet. Flat mode uses `research/_working/preliminary-ui-interview-research.md`; product-path mode uses `research/{slug}/_working/preliminary-ui-interview-research.md`. Existing raw evidence or search-log outputs may remain as supporting evidence when the skill contract already requires them, but synthesized deliverables stay in the working packet. Update the same `review` alignment page so it renders the full preliminary packet, evidence matrix, assumptions/confidence register, source coverage gaps, proposed canonical file changes, and artifact approval gates. Partial compiled responses revise the working packet and review page, then remain in Stage 2. Stage 3 consumes final compiled response YAML for artifact approval only when it has `approval_status: ready-for-agent-review` and no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Apply approved edits first, archive the working packet to `docs/history/archive/YYYY-MM-DD/HHMMSS/<original-working-path>`, remove the active working packet, write the approved canonical artifacts to the unchanged output paths, and convert the page to `confirmed` with the approval record preserved.
+**Staged research workflow.** Heavy report-first research uses a scope-first three-stage approval workflow. Stage 1 is minimal scope discovery only: inspect enough repository, user, and source context to propose research scope, source plan, assumptions, output paths, and approval questions. Build the `review` alignment page before synthesized research. The page must render the proposed scope, available source categories, known context, assumptions/confidence, proposed working-packet and canonical output paths, research-scope approval gates, and a `Stage 2 Preview / Expected Review Format` section that shows the future Stage 2 review shape before research starts. Stop for final compiled response YAML approval of the research scope. Do not synthesize findings, rank candidates, recommend a path, or create working packets, canonical research, spec, or task files in Stage 1. Stage 2 starts only after final compiled response YAML approves the research scope with no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Perform the synthesized research, run required source/code checks, and write only a non-canonical working packet. Flat mode uses `research/_working/preliminary-ui-interview-research.md`; product-path mode uses `research/{slug}/_working/preliminary-ui-interview-research.md`. Existing raw evidence or search-log outputs may remain as supporting evidence when the skill contract already requires them, but synthesized deliverables stay in the working packet. Update the same `review` alignment page so it renders the complete working-packet substance as structured HTML review UI: purpose-built sections, tables, matrices, gates, cards, and tier-appropriate charts or diagrams that preserve every packet section, finding, caveat, and decision detail without summary loss. Raw Markdown packet text may appear only as a supplemental source view after the rendered review UI; do not make a `Full Preliminary Packet` or `Full Working Packet` raw Markdown dump, giant `<pre><code>` block, link-only view, or source-only view the primary review surface. Include the evidence matrix, assumptions/confidence register, source coverage gaps, proposed canonical file changes, and artifact approval gates. Partial compiled responses revise the working packet and review page, then remain in Stage 2. Stage 3 consumes final compiled response YAML for artifact approval only when it has `approval_status: ready-for-agent-review` and no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Apply approved edits first, archive the working packet to `docs/history/archive/YYYY-MM-DD/HHMMSS/<original-working-path>`, remove the active working packet, write the approved canonical artifacts to the unchanged output paths, and convert the page to `confirmed` with the approval record preserved.
+
+**Stage 2 review-page template.** Stage 1 scope-review pages must include a `Stage 2 Preview / Expected Review Format` section that previews the exact section sequence, table shapes, evidence treatment, visual density, and approval gates the user will see after research; make it specific enough for the user to flag preferred content formats, grouping, labels, visuals, and evidence density before the agent does heavy research. After scope approval and research, the Stage 2 review page must include these sections as structured HTML, not as raw Markdown dumps: `Research Scope Approved` status block with approved scope, source plan, output paths, and unresolved caveats; `Executive Findings` or a skill-specific top-findings section with confidence labels; `Evidence Matrix` mapping claim, evidence/source/path, inference, confidence, assumptions, and decision impact; `Working Packet Review` with the complete working-packet substance rendered as purpose-built HTML sections, lists, tables, matrices, cards, and tier-appropriate charts or diagrams; `Alternatives / Rejected or Lower-Confidence Findings`; `Source Coverage & Gaps`; `Assumptions / Confidence Register`; `Proposed Canonical Artifacts & File Changes`; a required `User Format Preferences` gate asking whether the layout, tables, grouping, visuals, labels, and evidence density match expectations; and a required `Final Artifact Approval` gate for Stage 3 readiness. Raw Markdown packet text, search logs, or source notes may appear only as supplemental source views after the rendered review UI and never replace the Stage 2 review sections.
 
-**UI-specific gates.** Render surfaced assumptions, the UI or content requirements manifest, scope boundaries, output-location/change-scope decisions, and the coverage checkpoint as gates. In requirements-only mode, the content requirements manifest is the candidate/verdict gate and layout decisions must remain non-goals. Apply the shared artifact-destination/proposed-file-changes de-duplication rule: combine them into one visual gate when they ask only the same path-destination question, and render separate gates when destination approval differs from downstream mutation scope, timing, or allowed files.
+**UI-specific gates.** Render surfaced assumptions, the UI or content requirements manifest, scope boundaries, output-location/change-scope decisions, and the coverage checkpoint as gates. In requirements-only mode, the content requirements manifest is the candidate/verdict gate and layout decisions must remain non-goals. Every `ui-interview` review page must include a plain-language Interview Stage section that names the invocation, distinguishes requirements-only review from a live page-by-page interview, states what user/agent interview work has already happened or was inferred from approved upstream evidence, and tells the reviewer whether the next action is section feedback, compiled approval YAML, or resuming the interview. Every page must include Interview provenance with exactly one of `live-ui-interview`, `evidence-synthesis-with-explicit-skip`, or `invalid-missing-ui-interview`; upstream approval alone is not interview completion. Evidence-only pages must be labeled `evidence-synthesis review` and route unresolved decisions to a resumed `ui-interview`. Render the working packet as structured HTML sections, lists, and real HTML tables; do not use a single raw Markdown `<pre><code>` block as the primary review surface. Raw Markdown may appear only as a supplemental source view after the rendered packet. Apply the shared artifact-destination/proposed-file-changes de-duplication rule: combine them into one visual gate when they ask only the same path-destination question, and render separate gates when destination approval differs from downstream mutation scope, timing, or allowed files.
 
 **Prototype tier rendering.** This skill's alignment page uses the `prototype` tier. In addition to charts and diagrams, functional interactive components (clickable flows, live CSS previews, drag interactions) are permitted. Prototypes are ephemeral previews, not production code. Each interactive component must include a reset button that restores initial state. Interactive components must be self-contained within the HTML file with no external dependencies. Include all visual tier requirements (chart snippets, table fallbacks, aria-labels, toggles) plus: state isolation (no localStorage/sessionStorage persistence), clear "this is a preview" labeling, and graceful degradation when JavaScript is disabled.
 

package/packs/product-design/claude/ui-interview/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## v0.20 - 2026-06-13
+
+- Moved confirmed pre-prototype UI branch packets, requirements-only packets, and interview logs from `specs/` to `design/`.
+- Added flow-tree manifest updates for UI review status, artifact references, and approve/reject/retry branch decisions.
+- Updated upstream reads to prefer `design/user-flow-*`, `design/ux-variations-*`, and scoped flow-tree manifests.
+
+## v0.19 - 2026-06-12
+
+- Reframed default `ui-interview` work around a specific UX variation branch rather than the old requirements-only handoff from `user-flow-map`.
+- Added the four-step branch review loop: investigate touched flows and sibling variation/UI proposal coordination, design and render an HTML visual mockup, interview for alignment or retry, and record approve/reject/retry routing.
+- Added deliverable requirements for branch investigation notes, visual mockup feedback, branch decision records, and next variation/user-flow routing.
+
+## v0.18 - 2026-06-12
+
+- Replaced the remaining packet-dump wording with the shared structured HTML review UI contract for complete working-packet substance.
+- Required requirements-only runs to complete their own UI Assumptions Manifest and Content Requirements Manifest confirmations, with an explicit `evidence-synthesis review` exception only when the current user invocation asks to skip live questions.
+- Added Interview provenance values for review pages: `live-ui-interview`, `evidence-synthesis-with-explicit-skip`, and `invalid-missing-ui-interview`.
+
+## v0.17 - 2026-06-12
+
+- Required pre-approval alignment pages to state the current interview stage in plain language and to distinguish requirements-only review from a live page-by-page interview.
+- Required working packets to render as structured HTML sections/lists/tables, with raw Markdown previews allowed only as supplemental source views.
+
+## v0.16 - 2026-06-12
+
+- Standardized active pack and skill install guidance on `npx skillpacks install <pack-or-skill>` instead of agent-native `/pack install` or `$pack install` recommendations.
+
 ## v0.15 - 2026-06-11
 
 - Added npm-aware install-route wording for agent-work-admin and cross-pack recommendations while preserving Claude `/pack install ...` routes.

package/packs/product-design/claude/ui-interview/SKILL.md

@@ -2,9 +2,9 @@
 name: ui-interview
 description: Interview page by page to define a complete UI specification, including layout, hierarchy, controls, links, spacing, sizing, responsive behavior, visual states, and implementation-ready interface details — supports a requirements-only mode that establishes data, actions, and states without locking layout or component decisions
 type: planning
-version: v0.15
+version: v0.20
 argument-hint: "[optional: app, page, flow, feature, or draft UI]"
-interview_depth: full
+context_intake: deep
 visual_tier: prototype
 ---
 
@@ -12,13 +12,15 @@ visual_tier: prototype
 
 Invoke as `/ui-interview`.
 
-Use this skill when the user needs to turn a rough product idea, feature, page, wireframe, screenshot, or existing app surface into a detailed implementation-ready UI specification. This skill focuses on the interface itself: pages, regions, components, buttons, links, labels, spacing, element size, visual hierarchy, state, responsive layout, and accessibility.
+Use this skill when the user needs to turn a UX variation branch, rough product idea, feature, page, wireframe, screenshot, or existing app surface into a detailed implementation-ready UI specification. In the default product-design tree, this skill evaluates one proposed `/ux-variations` branch for one specific user flow, designs a proposed UI, renders an HTML visual mockup for alignment, and then records whether that branch is approved, rejected, or needs another mockup iteration before routing to the next UX variation or user flow.
 
-Use `/user-flow-map` before this skill when the product or feature has no credible screen/route inventory, task sequence, branch coverage, or state map. Prefer `specs/user-flow-*.md` as source material when it exists; it is the upstream flow-structure contract for requirements-only UI work.
+Use `/user-flow-map` before this skill when the product or feature has no credible screen/route inventory, task sequence, branch coverage, or state map. Prefer `design/user-flow-*.md` and the scoped flow-tree manifest as source material when they exist; they are the upstream wireframe-tree contract. Use `/ux-variations [specific-user-flow]` before this skill when a flow exists but no UX variation branch has been proposed yet.
 
-Use `/ux-variations` after this skill when the user wants multiple experience concepts or interface variants to compare before locking the final direction.
+Use `/ux-variations` after this skill only when the current UI mockup exposes a missing or rejected variation axis that needs branch exploration before another UI proposal.
 
-When invoked with `--requirements-only` (or when the user says "just requirements", "requirements only", or "content requirements"), this skill stops after establishing what the page needs — data, actions, states, and constraints — without committing to any layout, component, or spatial decisions. This mode feeds directly into `/ux-variations --layout-mode` to explore multiple concrete visual approaches for the same content contract.
+When invoked with `--requirements-only` (or when the user says "just requirements", "requirements only", or "content requirements"), this skill stops after establishing what the page needs — data, actions, states, and constraints — without committing to any layout, component, or spatial decisions. This is an explicit bounded mode, not the default route from `/user-flow-map`; use it when the user asks for a content contract or when a layout-mode variation run genuinely requires fixed page requirements.
+
+Default branch-review handoff guard: upstream `/user-flow-map` approval and `/ux-variations` output may provide source evidence, but they do not count as `ui-interview` approval. Upstream approval does not count as `ui-interview` interview completion. Requirements-only runs must still present and confirm its own UI Assumptions Manifest, then its own Content Requirements Manifest. `ui-interview` must still investigate cross-flow and cross-variation coordination, design a proposed UI, render the visual mockup in HTML, ask the user for alignment or feedback, and record an explicit approve/reject/retry branch decision.
 
 ## Process
 
@@ -34,15 +36,26 @@ Resolve research scope by product path before using code or app structure as a h
 6. If no product directories exist, use flat `research/` single-product mode.
 7. Detect monorepo/app/package structure only as a secondary hint. Suggest creating a missing `research/{slug}/` product path when code clearly exposes an app, but do not require code or monorepo detection before using `research/{slug}/`.
 
-When product path `{slug}` is active, read and write research under `research/{slug}/`, specs under `specs/{slug}/`, and treat top-level `research/*.md` files as flat-mode documents or cross-path summaries.
+When product path `{slug}` is active, read and write research under `research/{slug}/`, pre-prototype design artifacts under `design/{slug}/`, finalized post-prototype implementation specs under `specs/{slug}/`, and treat top-level `research/*.md` and `design/*.md` files as flat-mode documents or cross-path summaries.
+
+### 0b. Design Flow Tree Manifest
+
+Use `design/flow-tree.schema.json` as the machine-readable contract for the pre-prototype product-design tree.
+
+- Product-path mode reads and updates `design/{slug}/flow-tree-{topic}.yaml`.
+- Flat mode reads and updates `design/flow-tree-{topic}.yaml`.
+- Add one `ui_reviews[]` entry under the selected UX variation branch for each proposed UI review. Each entry must include `id`, `status`, artifact references, and `decision_id` when a decision is recorded.
+- Record approve/reject/retry decisions in the manifest `decisions[]` list. Do not write UX branch state to `research/.progress.yaml`; that file remains product-path/product-line tracking.
 
 1. **Resolve context**
    - Read `.agents/project.json` if it exists.
    - Read `README.md`, `AGENTS.md`, `CLAUDE.md`, relevant `docs/`, `specs/`, `research/`, route files, component directories, screenshots, and design artifacts when present.
-   - Prefer `specs/user-flow-*.md` (or product-path-scoped equivalents) for screen sequence, route inventory, branches, decisions, states, failure paths, and low-fidelity wireframe notes before inferring UI requirements.
+   - Prefer `design/user-flow-*.md` and `design/**/flow-tree-*.yaml` for screen sequence, route inventory, branches, decisions, states, failure paths, and low-fidelity wireframe notes before inferring UI requirements.
+   - Prefer `design/ux-variations-*.md` (or product-path-scoped equivalents) for the selected UX variation branch, sibling variations, unresolved branch decisions, proposed progression paths, and branch-routing expectations.
    - If the request is for an existing UI, inspect the current implementation before interviewing.
    - If multiple apps or surfaces are plausible, ask the user which app, flow, or page to cover first.
    - If the interface has no credible screen/flow structure from a user-flow spec, existing routes, screenshot, wireframe, or explicit user prompt, stop and recommend `/user-flow-map [topic]` before UI requirements or layout decisions.
+   - If the interface has a credible flow but no specific UX variation branch or proposal to judge, stop and recommend `/ux-variations [specific-user-flow]`.
 
 2. **Treat inputs as draft material**
    - Do not assume the current UI, prompt, screenshot, or mockup is final.
@@ -53,11 +66,19 @@ When product path `{slug}` is active, read and write research under `research/{s
 3. **Surface assumptions before probing**
    - Present a UI Assumptions Manifest before deep questioning.
    - Tag each assumption with `[from spec]`, `[from codebase]`, `[from research]`, `[from artifact]`, or `[inferred]`.
-   - Cover product and user context, pages and routes, primary tasks, navigation, hierarchy, layout grid, spatial density, component inventory, button and link semantics, form behavior, empty/loading/error/success states, responsive behavior, accessibility, visual language, implementation constraints, and the prototype-first boundary for new product or substantial feature work: what the user should be able to click through first, whether multiple route-based experiments should be built, what data can be fake, fixture-backed, or in-memory, and which infrastructure must be represented visually but not implemented yet.
+   - Cover product and user context, parent user flow, selected UX variation branch, other user flows touched by this branch, sibling UX variations or existing UI proposals this branch must coordinate with, pages and routes, primary tasks, navigation, hierarchy, layout grid, spatial density, component inventory, button and link semantics, form behavior, empty/loading/error/success states, responsive behavior, accessibility, visual language, implementation constraints, and the prototype-first boundary for new product or substantial feature work: what the user should be able to click through first, whether multiple route-based experiments should be built, what data can be fake, fixture-backed, or in-memory, and which infrastructure must be represented visually but not implemented yet.
    - Use AskUserQuestion to ask the user to confirm, correct, or flag assumptions before continuing.
    - Deliver every manifest/checklist/checkpoint the user must confirm inline as the final message text of its own turn; ask the confirmation question in the next turn. AskUserQuestion option previews may mirror the content as a supplement but are never the sole channel. Never emit it only as mid-turn text in a turn that ends with a tool call — harness rendering does not guarantee mid-turn text is shown. A confirmation question must never reference content the user has not been shown.
 
-4. **Interview page by page**
+4. **Branch review loop**
+   - In default mode, run this four-step loop for the selected UX variation branch:
+     1. Investigate the specific UX variation proposed for a specific user flow. Determine which other user flows it touches, which sibling UX variations it competes with or depends on, and which existing UI proposals, specs, prototypes, or implementation surfaces it must coordinate with.
+     2. Design a proposed UI for that branch and display a visual mockup in HTML. The mockup may be static or lightly interactive, but it must be concrete enough for the user to judge layout, hierarchy, controls, copy, state treatment, and branch viability.
+     3. Interview the user for alignment over the UI for this UX variation experiment. If the visual mockup is off-base, collect focused feedback, revise the proposal/mockup, and ask again instead of treating the first mockup as final.
+     4. Record whether this branch of the user flow is approved, rejected, or needs another iteration, then route to the next unresolved UX variation or user flow as needed.
+   - The branch decision is separate from implementation approval. Approval means the UI direction is a valid branch of the wireframe tree; implementation work still follows the project roadmap/shipping contract.
+
+5. **Interview page by page**
    - Ask 1 to 3 focused questions per turn using AskUserQuestion.
    - Move through the interface in this order unless the user asks otherwise:
      - Global shell: header, sidebar, footer, navigation, account controls, notifications
@@ -65,8 +86,10 @@ When product path `{slug}` is active, read and write research under `research/{s
      - Page purpose: user goal, task priority, and success condition
      - Prototype calibration: first clickable journey, route-based experiment set, fixture/fake data boundaries, infrastructure-only states to mock rather than implement, and taste/feel questions the prototype must answer before database, auth, payment, analytics, deployment, admin, or multi-tenant work is planned.
 
-4b. **Requirements gate (requirements-only mode)**
+5b. **Requirements gate (requirements-only mode)**
    - In requirements-only mode, stop here — do not proceed to layout anatomy, component inventory, or spatial decisions.
+   - Requirements-only mode has two required confirmation gates before any alignment page build: the UI Assumptions Manifest from step 3, then the Content Requirements Manifest in this step. Upstream approval, including approved `/user-flow-map` YAML or an approved flow alignment page, may populate assumptions and source evidence but cannot replace either confirmation; `ui-interview` must still present and confirm its own UI Assumptions Manifest, then its own Content Requirements Manifest.
+   - Evidence-synthesis exception: only skip live confirmation questions when the current visible user invocation explicitly asks to skip live interview questions, synthesize from existing evidence only, or avoid asking the user. In that case, label the output as an `evidence-synthesis review`, set Interview provenance to `evidence-synthesis-with-explicit-skip`, do not call it a completed interview, and route unresolved decisions to a resumed `/ui-interview` instead of implying interview completion.
    - For each page, confirm:
      - Data fields and entities (with cardinality: one, many, nested, polymorphic)
      - User actions (create, edit, delete, filter, sort, export, navigate, bulk-select, reorder)
@@ -75,13 +98,13 @@ When product path `{slug}` is active, read and write research under `research/{s
      - Content hierarchy (primary / secondary / tertiary information)
      - Relationships between data elements (parent-child, peer, reference, aggregate)
    - Present a **Content Requirements Manifest** summarizing all pages, then use AskUserQuestion to confirm. Deliver the manifest per the inline visibility rule in step 3 (turn-final message text of its own turn; confirmation question in the next turn; option previews only as a supplementary mirror), never as mid-turn text only.
-   - This manifest confirmation is non-final: it only confirms the requirements draft is ready for the pre-approval lifecycle in step 7. Route all writes through that lifecycle — working packet at `research/_working/preliminary-ui-interview-research.md` (or `research/{slug}/_working/preliminary-ui-interview-research.md`), then a `review`-state `alignment/ui-interview-{topic}.html` page rendering the Content Requirements Manifest as the candidate/verdict gate, then final compiled YAML approval.
-   - Only after final compiled YAML approval, write `specs/ui-requirements-[topic].md` (content requirements) and `ui-requirements-[topic]-interview.md` (interview log), archive the working packet, and convert the page to `confirmed` per step 7.
+   - This manifest confirmation is non-final: it only confirms the requirements draft is ready for the pre-approval lifecycle in step 9. Route all writes through that lifecycle — working packet at `research/_working/preliminary-ui-interview-research.md` (or `research/{slug}/_working/preliminary-ui-interview-research.md`), then a `review`-state `alignment/ui-interview-{topic}.html` page rendering the Content Requirements Manifest as the candidate/verdict gate, then final compiled YAML approval.
+   - Only after final compiled YAML approval, write `design/ui-requirements-[topic].md` (content requirements) and `design/ui-requirements-[topic]-interview.md` (interview log) in flat mode or product-path-scoped equivalents, update the scoped flow-tree manifest, archive the working packet, and convert the page to `confirmed` per step 9.
    - Only after the page is converted to `confirmed` and canonical files are written, recommend `/ux-variations --layout-mode` to explore multiple visual approaches for these requirements, or `/ui-interview` (full mode, no flag) to proceed directly to a single deep UI specification.
    - If requirements-only work exposes missing screen order, branch decisions, or state coverage, recommend `/user-flow-map [topic]` instead of inventing layout variants.
-   - Stop. Do not continue to step 5 or beyond; the pre-approval lifecycle in step 7 and the requirements deliverables above are the only remaining work in this mode.
+   - Stop. Do not continue to step 6 or beyond; the pre-approval lifecycle in step 9 and the requirements deliverables above are the only remaining work in this mode.
 
-5. **Full UI specification** (no `--content-only` flag):
+6. **Full UI specification** (no `--content-only` flag):
 
    - Layout anatomy: top-to-bottom and left-to-right regions, alignment, density, scroll behavior
      - Component inventory: tables, lists, cards, forms, charts, media, editors, maps, canvases
@@ -93,24 +116,27 @@ When product path `{slug}` is active, read and write research under `research/{s
      - Accessibility: keyboard order, focus traps, labels, contrast, reduced motion, screen reader names. Include color-blind safe patterns, keyboard navigation, reduced motion support, and screen reader labels by default in every spec. Do not present accessibility features as optional checkboxes. Only ask about domain-specific accessibility (gamepad support, dyslexia fonts) when the product context warrants it.
    - When a page includes repeated items, define one canonical item and its variations rather than asking about every row individually.
 
-5. **Research and recommend by default**
+7. **Research and recommend by default**
    - Use project evidence and established UI conventions before asking the user to invent details.
    - For material decisions, present options, a recommendation, rationale, tradeoffs, and mitigation.
    - Recommend familiar controls over novel patterns unless the product has a strong reason to deviate.
    - Respect the existing design system, component library, and implementation patterns.
    - Reference and inspiration questions ("apps you admire?") are low-priority. Ask once early, accept any answer including "none" or "let's experiment," and move on. Do not block the interview on reference input.
 
-6. **Coverage checkpoint**
+8. **Coverage checkpoint**
    - Before concluding, use AskUserQuestion to present a concise checklist of pages, components, controls, states, responsive behavior, and unresolved risks.
    - Deliver the checklist per the inline visibility rule in step 3 (turn-final message text of its own turn; confirmation question in the next turn; option previews only as a supplementary mirror), never as mid-turn text only.
    - Ask whether anything is missing or should be revisited before building the alignment page.
-   - This confirmation is non-final: it only establishes that the draft is ready for the pre-approval lifecycle in step 7. It does not authorize canonical spec writes.
-
-7. **Build pre-approval alignment page**
-   - Before writing any canonical `specs/ui-[topic].md`, `specs/ui-requirements-[topic].md`, or interview log, write the full draft (spec or requirements content plus interview record) only to the working packet `research/_working/preliminary-ui-interview-research.md` (or `research/{slug}/_working/preliminary-ui-interview-research.md` when a product path is active).
-   - Build `alignment/ui-interview-{topic}.html` as a `review`-state page rendering the full working packet — manifest, page-by-page decisions, coverage checkpoint, proposed canonical file destinations — and the approval gates.
+   - This confirmation is non-final: it only establishes that the draft is ready for the pre-approval lifecycle in step 9. It does not authorize canonical spec writes.
+
+9. **Build pre-approval alignment page**
+   - Before writing any canonical `design/ui-[topic].md`, `design/ui-requirements-[topic].md`, or interview log, write the full draft (spec or requirements content plus interview record) only to the working packet `research/_working/preliminary-ui-interview-research.md` (or `research/{slug}/_working/preliminary-ui-interview-research.md` when a product path is active).
+   - Build `alignment/ui-interview-{topic}.html` as a `review`-state page rendering the complete working-packet substance as structured HTML review UI: the manifest, branch investigation, HTML visual mockup, page-by-page decisions, coverage checkpoint, proposed canonical file destinations, and approval/rejection gates.
+   - Include **Interview provenance** in the page and working packet with exactly one of these values: `live-ui-interview` when this run completed the required manifest confirmations with the user; `evidence-synthesis-with-explicit-skip` when the current invocation explicitly asked to skip live questions or synthesize from evidence; `invalid-missing-ui-interview` when neither condition is true. `invalid-missing-ui-interview` pages must route unresolved decisions to a resumed `/ui-interview` and must not imply interview completion or readiness for canonical writes.
+   - At the top of the page, include a plain-language **Interview stage** explainer naming the invocation, whether the run is requirements-only, full UI mode, or branch-review mode, what user/agent interview work has already happened or was inferred from approved upstream evidence, and what the reviewer should do next. If requirements were synthesized primarily from approved specs or code evidence rather than live Q&A, say so directly and route missing answers through section feedback or a resumed interview instead of implying the interview is complete.
+   - Render the working packet as structured HTML, not as a raw Markdown preview: headings become sections, lists stay readable lists, and every Markdown table becomes an HTML `<table>` inside a `.table-wrap` container with a concise `data-tts-narrative`. A raw Markdown `<pre><code>` dump may appear only as a supplemental source view after the rendered packet, never as the primary review surface.
    - Attempt to open the page in the browser and point the user at the repo-relative path.
-   - Treat every AskUserQuestion checkpoint confirmation in steps 3–6 as non-final; each only confirms the draft is ready for review. Only final compiled YAML from the alignment page authorizes canonical writes.
+   - Treat every AskUserQuestion checkpoint confirmation in steps 3–8 as non-final; each only confirms the draft is ready for review. Only final compiled YAML from the alignment page authorizes canonical writes.
    - When feedback-only YAML is provided, revise the working packet and the alignment page, then ask again; the work stays pre-approval.
    - Before final compiled YAML approval, the next action is review or revision of the HTML alignment page. Do not include `Recommended next skill`, `Recommended next command`, or downstream routing language until after final compiled YAML approval has been provided and the approved canonical files have been written.
 
@@ -118,22 +144,23 @@ When product path `{slug}` is active, read and write research under `research/{s
 
 Before writing anything in this section, verify the alignment page has final compiled YAML approval. Do not write canonical UI specs or interview logs until `alignment/ui-interview-{topic}.html` has been reviewed and the user has provided final compiled YAML approval; checkpoint confirmations are not final approval and do not authorize these writes.
 
-- Write the completed UI specification to `specs/ui-[topic].md`.
-- Write the interview log to `ui-[topic]-interview.md`.
+- Write the completed UI branch packet to `design/ui-[topic].md` in flat mode or `design/{slug}/ui-[topic].md` in product-path mode.
+- Write the interview log to `design/ui-[topic]-interview.md` in flat mode or `design/{slug}/ui-[topic]-interview.md` in product-path mode.
+- Update the scoped flow-tree manifest with the UI review status, artifact references, and approve/reject/retry decision record.
 
 After the canonical files are written, archive the working packet to `docs/history/archive/YYYY-MM-DD/HHMMSS/<original-working-path>`, remove the active working packet, and convert the alignment page from `review` to `confirmed`.
 
-The UI specification must include source evidence, the confirmed UI Assumptions Manifest, page inventory, route map, global shell rules, page-by-page anatomy, component inventory, control inventory, link inventory, layout and responsive rules, visual style direction, interaction states, accessibility requirements, implementation notes, open questions, risks, and non-goals. For new product interfaces or substantial feature interfaces, include a prototype-first section naming the first clickable journey, experiment route map when multiple alternatives should be tested, fake/fixture data, visually mocked infrastructure states, deferred production infrastructure, and the evidence required before implementation planning promotes any deferred infrastructure.
+The UI specification must include source evidence, the confirmed UI Assumptions Manifest, parent user flow, selected UX variation branch, touched sibling flows, coordination dependencies, HTML visual mockup path or embedded review section for the proposed UI, branch decision record (approved, rejected, or retry needed) with next branch/user-flow route, page inventory, route map, global shell rules, page-by-page anatomy, component inventory, control inventory, link inventory, layout and responsive rules, visual style direction, interaction states, accessibility requirements, implementation notes, open questions, risks, and non-goals. For new product interfaces or substantial feature interfaces, include a prototype-first section naming the first clickable journey, experiment route map when multiple alternatives should be tested, fake/fixture data, visually mocked infrastructure states, deferred production infrastructure, and the evidence required before implementation planning promotes any deferred infrastructure.
 
-The interview log must include the manifest, every question asked, options and recommendations presented, user responses, final decisions, and notable changes from the initial draft, current implementation, or artifact.
+The interview log must include the manifest, branch investigation notes and cross-flow/variation coordination findings, visual mockup feedback, retry notes, final branch decision, every question asked, options and recommendations presented, user responses, final decisions, and notable changes from the initial draft, current implementation, or artifact.
 
-Only after the page is converted to `confirmed` and canonical files are written, recommend `/ux-variations` if variants are needed before implementation, or check `.agents/project.json.enabled_packs` for `agent-work-admin` — if `agent-work-admin` is not enabled, recommend `/pack install agent-work-admin` inside Claude Code, or `npx skillpacks install agent-work-admin` from the project shell, first; if `agent-work-admin` is enabled, recommend `/roadmap` — if the interface is ready to sequence into work.
+Only after the page is converted to `confirmed` and canonical files are written, route based on the branch decision: recommend `/ui-interview [next-specific-ux-variation]` for the next UX variation branch, `/ux-variations [next-specific-user-flow]` when the next user flow still needs progression variants, or check `.agents/project.json.enabled_packs` for `agent-work-admin` — if `agent-work-admin` is not enabled, recommend `npx skillpacks install agent-work-admin` from the project shell, first; if `agent-work-admin` is enabled, recommend `/roadmap` — if the approved branch is ready to sequence into implementation work.
 
 ### Alignment Page
 
 When this skill produces durable deliverables (research, specs, plans, reports, prototypes, or any document output), build a full-depth HTML alignment page following `ALIGNMENT-PAGE.md` in this skill's directory. Output: `alignment/ui-interview-{topic}.html`.
 
-The page is built pre-approval in `review` state per step 7, before any canonical spec write, and converts to `confirmed` only after final compiled YAML approval and canonical writes.
+The page is built pre-approval in `review` state per step 9, before any canonical spec write, and converts to `confirmed` only after final compiled YAML approval and canonical writes.
 
 ## Constraints
 
@@ -141,11 +168,14 @@ The page is built pre-approval in `review` state per step 7, before any canonica
 - Do not collapse UI detail into generic phrases such as "standard dashboard layout" or "normal form behavior."
 - Do not create implementation plans until the page anatomy and control behavior are decision-complete.
 - Do not treat visual polish as separate from implementation. Size, spacing, hierarchy, and responsive behavior must be specified well enough for a developer to build.
-- When recommending a skill from another pack, verify the pack is installed via `.agents/project.json` `enabled_packs`. If not installed, recommend `/pack install <pack-name>` inside Claude Code, or `npx skillpacks install <pack-name>` from the project shell, before the target skill.
+- Do not treat upstream `ux-variations` output as UI approval. The branch still needs an HTML visual mockup and explicit approve/reject/retry decision.
+- Do not route to broad implementation planning while unresolved UX variation branches or touched user flows still need review.
+- Do not write pre-prototype UI branch packets to `specs/`. `design/` is the canonical home for flow maps, UX variation plans, UI branch packets, branch decisions, mockup references, and flow-tree manifests.
+- When recommending a skill from another pack, verify the pack is installed via `.agents/project.json` `enabled_packs`. If not installed, recommend `npx skillpacks install <pack-name>` from the project shell, before the target skill.
 
 ## Archive-First Replacement Policy
 
-- Before replacing or substantively rewriting an existing canonical research/spec document (`research/**/*.md`, `specs/**/*.md`, or `docs/specifications/**/*.md`), copy the current file to `docs/history/archive/YYYY-MM-DD/HHMMSS/<original-relative-path>`.
+- Before replacing or substantively rewriting an existing canonical research/design/spec document (`research/**/*.md`, `design/**/*.md`, `specs/**/*.md`, or `docs/specifications/**/*.md`), copy the current file to `docs/history/archive/YYYY-MM-DD/HHMMSS/<original-relative-path>`.
 - Preserve the archived snapshot exactly as it existed before the change; do not edit the archived copy after creating it.
 - After the archive snapshot exists, write the updated document to the original canonical path.
 - Report both the archive path and the updated canonical path in the final output.