skillpacks 0.1.1 → 0.1.2

package/packs/product-design/codex/spec-interview/archive/v0.12/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: spec-interview
+description: Post-prototype production deep dive — walks through consolidated prototype screen by screen to extract production specifications
+type: planning
+version: v0.12
+argument-hint: "[--ideas]"
+interview_depth: full
+---
+
+## 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 `$pack install <pack>` inside Codex, or `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
+
+Invoke as `$spec-interview`.
+
+Use this skill when the user has a consolidated prototype and research context that needs to be turned into a complete production implementation specification. 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.
+   - Check `.agents/project.json` first. If it exists, use `project_type` and `enabled_packs` to choose the right research frame:
+     - `business-app` → use business research artifacts such as `research/icp.md`.
+     - `game` → use game artifacts such as `research/game-audience.md`, `research/game-fantasy.md`, and `research/game-core-loop.md`.
+     - `devtool` → use devtool artifacts such as `research/devtool-user-map.md`, `research/devtool-dx-journey.md`, and `research/devtool-integration-map.md`.
+   - If project type is missing or mismatched, recommend `$pack recommend`, `$pack install <pack>` inside Codex, or `npx skillpacks install <pack>` from the project shell before doing domain-specific planning.
+   - For business-app projects, check if `research/idea-brief.md`, `research/icp.md`, and `research/journey-map.md` exist. Read them as source evidence — ground implementation decisions against the concept constraints, ICP, user journey, customer journey, technical sophistication, customer provisioning model, path to aha, conversion path, retention loop, and champion dynamics. If lifecycle evidence is missing and the `customer-lifecycle` pack is not enabled, recommend `$pack install customer-lifecycle` inside Codex, or `npx skillpacks install customer-lifecycle` from the project shell, before `$journey-map`. Flag conflicts (e.g., "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.
+   - 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 or command call. In the next turn, ask the user to confirm or correct it together with one focused interview question so momentum is kept. 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, 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?
+   - Codex interview cadence: ask one primary decision question per turn by default. Use short follow-up bullets only when they clarify the same decision, not to batch unrelated questions.
+   - If the session is already in Plan mode, `request_user_input` may present 2-3 real options for the current material decision. Otherwise ask one concise direct question in plain text.
+   - **Research and recommend by default.** Use web search, upstream research docs, and codebase analysis to gather evidence before asking the user. Assume the user has no insider knowledge unless they explicitly provide it. Present findings with data, define relevant terms, state a recommendation with reasoning, and ask the user to approve, adjust, or override based on hard constraints, proprietary facts, or corrections. Only present options without a recommendation when internal constraints, preferences, or missing facts make evidence insufficient. For each real choice:
+     - Explain the options with evidence
+     - Give a brief pros and cons comparison
+     - State a recommendation and why
+     - Explain how to mitigate the recommended option's downside when useful
+
+4. **Iterative prototype updates:**
+   - When the interview reveals gaps in the prototype (missing screens, unclear flows, absent states), ask: "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 implementation goals, architecture, data models, APIs/contracts, migrations, edge cases, security, performance, observability, test strategy, and scope boundaries are all covered.
+   - **Coverage checkpoint** — Before concluding, present a structured summary inline as the final message text of its own turn: list each area covered with key decisions made and the evidence/reasoning that supported each. In the next turn, ask: "Does this cover everything? Any constraints, missing facts, or areas to revisit?"
+
+## Deliverables
+
+- Write the completed specification to `specs/[topic].md` (create the `specs/` directory if needed), 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.
+- Write an interview log to `[topic]-interview.md`
+
+The interview log should include:
+
+- The Assumptions Checkpoint as presented, with user corrections noted
+- Each question asked
+- Options presented, if any
+- The user's responses and chosen direction
+- A closing summary of significant deviations from the initial draft and why they changed
+
+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.
+
+### 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
+
+- Do not assume draft text is final.
+- Keep probing until the spec is decision-complete enough to implement.
+
+## Ideas Mode (`--ideas`)
+
+When `$ARGUMENTS` contains `--ideas`, read `tasks/ideas.md` and run the interview process for each idea sequentially.
+
+1. Read `tasks/ideas.md` and extract every distinct idea entry. If a filter keyword is provided, 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".
+6. If the user stops partway through, write deliverables for completed ideas and note which remain.
+
+Do not repeat work already in `tasks/roadmap.md`, `tasks/todo.md`, or `specs/`.
+
+## 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/codex/spec-interview/archive/v0.13/SKILL.md

@@ -0,0 +1,159 @@
+---
+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: "[--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
+
+Invoke as `$spec-interview`.
+
+Use this skill when the user has a consolidated prototype and research context that needs to be turned into a complete production implementation specification. 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.
+   - Check `.agents/project.json` first. If it exists, use `project_type` and `enabled_packs` to choose the right research frame:
+     - `business-app` → use business research artifacts such as `research/icp.md`.
+     - `game` → use game artifacts such as `research/game-audience.md`, `research/game-fantasy.md`, and `research/game-core-loop.md`.
+     - `devtool` → use devtool artifacts such as `research/devtool-user-map.md`, `research/devtool-dx-journey.md`, and `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.
+   - For business-app projects, check if `research/idea-brief.md`, `research/icp.md`, and `research/journey-map.md` exist. Read them as source evidence — ground implementation decisions against the concept constraints, ICP, user journey, customer journey, technical sophistication, customer provisioning model, path to aha, conversion path, retention loop, and champion dynamics. 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`. Flag conflicts (e.g., "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.
+   - 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 or command call. In the next turn, ask the user to confirm or correct it together with one focused interview question so momentum is kept. 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, 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?
+   - Codex interview cadence: ask one primary decision question per turn by default. Use short follow-up bullets only when they clarify the same decision, not to batch unrelated questions.
+   - If the session is already in Plan mode, `request_user_input` may present 2-3 real options for the current material decision. Otherwise ask one concise direct question in plain text.
+   - **Research and recommend by default.** Use web search, upstream research docs, and codebase analysis to gather evidence before asking the user. Assume the user has no insider knowledge unless they explicitly provide it. Present findings with data, define relevant terms, state a recommendation with reasoning, and ask the user to approve, adjust, or override based on hard constraints, proprietary facts, or corrections. Only present options without a recommendation when internal constraints, preferences, or missing facts make evidence insufficient. For each real choice:
+     - Explain the options with evidence
+     - Give a brief pros and cons comparison
+     - State a recommendation and why
+     - Explain how to mitigate the recommended option's downside when useful
+
+4. **Iterative prototype updates:**
+   - When the interview reveals gaps in the prototype (missing screens, unclear flows, absent states), ask: "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 implementation goals, architecture, data models, APIs/contracts, migrations, edge cases, security, performance, observability, test strategy, and scope boundaries are all covered.
+   - **Coverage checkpoint** — Before concluding, present a structured summary inline as the final message text of its own turn: list each area covered with key decisions made and the evidence/reasoning that supported each. In the next turn, ask: "Does this cover everything? Any constraints, missing facts, or areas to revisit?"
+
+## Deliverables
+
+- Write the completed specification to `specs/[topic].md` (create the `specs/` directory if needed), 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.
+- Write an interview log to `[topic]-interview.md`
+
+The interview log should include:
+
+- The Assumptions Checkpoint as presented, with user corrections noted
+- Each question asked
+- Options presented, if any
+- The user's responses and chosen direction
+- A closing summary of significant deviations from the initial draft and why they changed
+
+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.
+
+### 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
+
+- Do not assume draft text is final.
+- Keep probing until the spec is decision-complete enough to implement.
+
+## Ideas Mode (`--ideas`)
+
+When `$ARGUMENTS` contains `--ideas`, read `tasks/ideas.md` and run the interview process for each idea sequentially.
+
+1. Read `tasks/ideas.md` and extract every distinct idea entry. If a filter keyword is provided, 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".
+6. If the user stops partway through, write deliverables for completed ideas and note which remain.
+
+Do not repeat work already in `tasks/roadmap.md`, `tasks/todo.md`, or `specs/`.
+
+## 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/codex/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/codex/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 Codex `$pack install ...` routes.