skillpacks 0.1.0

package/packs/product-testing/codex/uat/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+## v0.10 - 2026-06-10
+
+- Converted the hand-authored alignment-page section to the generator-owned stub plus a bundled `ALIGNMENT-PAGE.md`; the page contract now follows the full shared convention (lifecycle states, central alignment index, section feedback, gate/feedback YAML, TTS, browser open) with the uat-specific gates from the generator gate map.
+- Gained the shared glossary additions gate from the convention (applies because the skill is `type: analysis`).
+
+## v0.9 - 2026-06-07
+
+- Routed missing-discovery UAT handoffs from the retired `$icp` executable to `$customer-discovery` while preserving `research/icp.md` as evidence input.
+
+## v0.8 - 2026-06-05
+
+- Changed alignment-page section feedback so the positive option is `emphasize` with `feedback: emphasize` and `requested_agent_action: add-weight-to-section`, making it a revision/weighting request instead of approval as-is.
+
+
+## v0.7 - 2026-05-31
+
+- Required alignment pages to use a top in-flow Table of Contents instead of sidebar navigation, and to avoid sticky/fixed bottom compile banners.
+- Restored bottom `Compile Feedback YAML` aggregation while keeping local section feedback YAML controls under selected section feedback textareas.
+
+## v0.6 - 2026-05-31
+
+- Kept final `Compile Answers` at the bottom while moving feedback-only YAML display/copy controls under each selected section feedback textarea.
+- Clarified that section thumbs up/down/clarify selections always reveal their own multiline feedback textarea even when the section also has gate-question inputs.
+
+## v0.5 - 2026-05-31
+
+- Added top-level `alignment_page` to feedback-only and final compiled YAML so agents can reopen the exact HTML review page.
+
+## v0.4 - 2026-05-30
+
+- Added feedback-only YAML alignment-page handling so section concerns and clarification requests can be sent before final gate answers.
+
+## v0.3 - 2026-05-30
+
+- Added product-path scope resolution that prefers non-archived `research/{slug}/` paths and active manifest paths before code or monorepo hints.
+- Excluded `research/_archive/`, legacy `abandoned`, `archived`, `deferred`, `revisit_candidate`, and `promoted` paths from active target selection while preserving flat `research/*.md` compatibility.
+
+
+## v0.0
+
+- Archived previous skill contract.
+
+## v0.2 - 2026-05-27
+
+- Added an explicit local alignment preview gate before UAT plan, variant-evaluation, and manual task writes.
+
+## v0.1 - 2026-05-25
+
+- Added research-quality alignment requirements covering claim/evidence/inference separation, no-context-loss HTML translation, evidence matrices, confidence/assumption registers, source coverage, and research completeness gates.

package/packs/product-testing/codex/uat/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: uat
+description: Create user acceptance test journeys from a target user's perspective, with role-based scenarios, acceptance criteria, and evidence capture
+type: analysis
+version: v0.10
+argument-hint: "[--variant-evaluation] [optional: persona, feature, release, journey, app, or variation spec]"
+interview_depth: none
+---
+
+## 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>` 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.
+
+# UAT
+
+Invoke as `$uat`.
+
+Create a user acceptance testing plan from the perspective of a potential or target user. Read the product surface, specs, journeys, stories, roadmap, and relevant research, then produces realistic end-to-end user journeys that validate whether the product satisfies user goals.
+
+UAT is not dogfooding. Dogfood asks how the app owner can adopt the product into their own workflow to understand and evaluate it. UAT asks whether a target user can complete meaningful real-world journeys and would accept the product as fit for use.
+
+This is a human-run acceptance plan, not automated testing. Do not start servers, drive browsers, call APIs, create accounts, or perform the scenarios yourself.
+
+When invoked with `--variant-evaluation` (or when the user asks to test/review UI variants), create a hands-on evaluation plan for built UX/UI variants before `$consolidate-variations`. This mode helps the user try each variant in a comparable way and capture enough evidence to form a defensible consolidation opinion.
+
+## 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. **Resolve project context**
+   - Read `.agents/project.json` if it exists.
+   - Use `project_type` and `enabled_packs` when present.
+   - If project metadata is missing, infer the project type from repo signals:
+     - business-app: SaaS, marketplace, productivity, workflow, enterprise, or user-facing app
+     - devtool: SDK, CLI, API, library, infrastructure, docs, examples, or package-first developer workflow
+     - game: game engine files, playable prototypes, store assets, or game-specific README/spec language
+     - generic: no strong domain signal
+   - Read `README.md`, `AGENTS.md`, `CLAUDE.md`, relevant `docs/`, `specs/`, `spec.md`, and `tasks/` files when present.
+
+2. **Load user evidence**
+   - Business app: read `research/icp.md`, `research/journey-map.md`, `research/customer-feedback.md`, `research/metrics.md`, and `research/mvp-gap.md` when present.
+   - Devtool: read `research/devtool-user-map.md`, `research/devtool-dx-journey.md`, `research/devtool-integration-map.md`, docs, examples, and package manifests when present.
+   - Game: read `research/game-audience.md`, `research/game-fantasy.md`, `research/game-core-loop.md`, `research/game-prototype-test.md`, and `research/game-playtest-metrics.md` when present.
+   - Generic: use specs, README, routes, tests, examples, issue descriptions, and task acceptance criteria.
+   - In product-path workspaces with `research/{slug}/` or `specs/{slug}/`, produce product-path-scoped UAT journeys for the requested app. If no app is specified and multiple apps are plausible, ask the user to choose.
+
+2b. **Variant evaluation mode**
+   - Trigger this branch when invoked with `--variant-evaluation`, when `specs/ui-layout-variations-*.md` exists for the requested topic, or when the user asks how to test/review built variants.
+   - Read `specs/ui-layout-variations-[topic].md`, `specs/ux-variations-[topic].md`, `specs/ui-requirements-[topic].md`, built variant routes/components, and any existing `research/uat-variant-evaluation-[topic].md`.
+   - Identify each variant, its intended thesis, implementation location, and the target user task it should support.
+   - Create comparable journeys that make the user perform the same core task in every variant, then capture variant-specific strengths, friction, confidence, and rejection signals.
+   - Include a side-by-side comparison matrix and a "Ready for `$consolidate-variations`?" checklist.
+   - Human execution still belongs in `tasks/manual-todo.md`; this skill writes the plan and manual tasks, but does not run the variants.
+   - After writing files, recommend `$consolidate-variations` only as the next step after the manual evaluation tasks are completed or when the user explicitly says they have already evaluated the variants.
+   - Stop after this branch. Do not generate generic target-user acceptance journeys unless the user also requested them.
+
+3. **Define acceptance perspective**
+   - Identify 1-3 target user personas or roles from the evidence.
+   - For each selected persona, define the job-to-be-done, context, goal, constraints, and acceptance threshold.
+   - Prefer external target users, buyers, evaluators, administrators, developers, or players over the product owner unless the owner is also the target user.
+   - If the target user is unclear, stop and recommend `$customer-discovery`, `$journey-map`, or the relevant pack research skill. For `$customer-discovery`, `$journey-map`, and other pack-based skills, apply the Pack Availability Guard — if the target skill's pack is not in `.agents/project.json` `enabled_packs`, recommend `$pack install <pack>` before the skill.
+
+4. **Create UAT journeys**
+   - Generate 3-7 journeys unless the user requested a narrower focus.
+   - Cover at least one critical happy path, one realistic obstacle or recovery path, and one return-use or handoff path when supported by the product evidence.
+   - Each journey must include:
+     - target user
+     - user goal
+     - real-world trigger
+     - setup and preconditions
+     - end-to-end task sequence
+     - expected user-visible success state
+     - acceptance criteria
+     - non-acceptance signals
+     - evidence to capture
+     - tester notes prompt
+     - follow-up routing
+   - Use concrete product language from specs and journeys. Avoid vague instructions such as "verify the feature works."
+
+5. **Classify follow-up work**
+   - Human-run UAT journeys go in `tasks/manual-todo.md` under `## UAT Journeys`.
+   - Use `_(after: research/uat-plan.md)_` unless the journey blocks or follows a known roadmap step. If tied to a known step, use `_(blocks: Step N.X)_` or `_(after: Step N.X)_`.
+   - Do not put human-run UAT journeys in `tasks/todo.md`.
+   - Implementation or documentation fixes discovered after a completed UAT run belong in `tasks/todo.md`, but do not invent fixes before the user journey has been attempted.
+   - One-time evidence collection belongs in `tasks/record-todo.md`.
+   - Recurring release acceptance checks belong in `tasks/recurring-todo.md` only when there is a clear release cadence.
+   - If a journey needs click-by-click help for a human-only external blocker, recommend `$guide`.
+
+6. **Present findings before writing when risk is high**
+   - If source material is thin, contradictory, or missing target-user evidence, summarize the gap and ask whether to proceed with assumptions.
+   - If source material is sufficient, write the plan and task sections directly.
+
+## Deliverables
+
+- `research/uat-plan.md` - persona assumptions, journey matrix, source evidence, acceptance checklist, result log template, and follow-up guidance.
+- In variant evaluation mode: `research/uat-variant-evaluation-[topic].md` - variant inventory, task script, comparison matrix, result logs, and consolidation readiness checklist.
+- `tasks/manual-todo.md` - append or replace only the `## UAT Journeys` section.
+- `tasks/recurring-todo.md` - optional, only when recurring UAT is useful and not already tracked.
+
+If `tasks/manual-todo.md` does not exist, create it with a `# Manual Tasks - [Project Name]` title, a short note that these items require human-only action, and the UAT section. Preserve all non-UAT sections when updating an existing file.
+
+Use this journey format in `research/uat-plan.md`:
+
+```markdown
+### Journey N: [Name]
+
+- Target user: [persona or role]
+- User goal: [what the user is trying to accomplish]
+- Trigger: [real-world reason the user starts]
+- Setup: [accounts, data, environment, permissions, or sample state needed]
+- Task sequence:
+  - [step the human tester performs as the target user]
+- Expected success state: [observable user-visible result]
+- Acceptance criteria:
+  - [ ] [specific criterion]
+- Non-acceptance signals: [confusion, delay, missing affordance, incorrect result, trust issue, or blocker]
+- Evidence to capture: [screenshots, recordings, notes, timestamps, records, command output, or artifacts]
+- Tester notes prompt: [question that captures whether the target user would accept this]
+- Follow-up routing: [manual note, $customer-discovery, $journey-map, $guide, or task promotion guidance]
+
+#### UAT result log
+
+- Status: Not run | Pass | Fail | Blocked
+- Evidence captured:
+- Tester notes:
+- Follow-up tasks promoted:
+```
+
+Use this variant evaluation format in `research/uat-variant-evaluation-[topic].md`:
+
+```markdown
+## Variant Evaluation Plan
+
+### Variant Inventory
+
+| Variant | Implementation location | Thesis | Primary task |
+|---|---|---|---|
+
+### Shared Evaluation Script
+
+- Target user:
+- Scenario:
+- Setup:
+- Core task sequence:
+- Success criteria:
+- Non-acceptance signals:
+- Evidence to capture:
+
+### Per-Variant Result Log
+
+#### [Variant name]
+
+- Status: Not run | Pass | Fail | Blocked
+- Evidence captured:
+- What worked:
+- What felt wrong:
+- Time/friction notes:
+- Keep for consolidation:
+- Reject for consolidation:
+- Confidence: Low | Medium | High
+
+### Side-by-Side Comparison Matrix
+
+| Dimension | Variant A | Variant B | Variant C | Current preference | Evidence |
+|---|---|---|---|---|---|
+
+### Ready for `$consolidate-variations`?
+
+- [ ] Every built variant has been tried or explicitly skipped.
+- [ ] Evidence exists for each kept/rejected design element.
+- [ ] Open blockers are documented.
+- [ ] The user has enough confidence to converge.
+```
+
+Use this item format in `tasks/manual-todo.md`:
+
+```markdown
+## UAT Journeys
+
+- [ ] Run UAT journey: [Journey name] as [target user] _(after: research/uat-plan.md)_ - capture evidence in `research/uat-plan.md`.
+```
+
+## Task Classification
+
+- Human UAT journey execution goes in `tasks/manual-todo.md`.
+- Variant evaluation tasks go in `tasks/manual-todo.md` under `## UAT Journeys` and should reference `research/uat-variant-evaluation-[topic].md`.
+- Immediate implementation or documentation fixes confirmed by completed UAT go in `tasks/todo.md`.
+- One-time condition-gated evidence collection goes in `tasks/record-todo.md`.
+- Release-cadence UAT checks go in `tasks/recurring-todo.md`.
+- Do not put non-blocking records or recurring obligations in `tasks/todo.md` unless they have been explicitly promoted into current execution work.
+
+## Constraints
+
+- Do not run or operate the product in this skill.
+- Do not start dev servers, launch browsers, use Playwright, call APIs, create accounts, or perform CLI workflows.
+- Do not mark journeys complete; only a human tester can do that after performing them.
+- Do not recommend `$consolidate-variations` before variant evaluation evidence exists, unless the user explicitly confirms they have already reviewed the variants and are ready to converge.
+- Do not duplicate existing unchecked UAT or manual tasks. Reference existing items when they already cover the same journey.
+- Prefer evidence-backed target-user journeys over exhaustive feature coverage.
+- Keep dogfood and UAT separate: use `$dogfood` for owner/operator adoption into the builder's workflow; use `$uat` for target-user acceptance journeys.
+- If no credible user journey, story, spec, or product surface can be found, stop and recommend `$customer-discovery`, `$journey-map`, or the relevant pack research skill. Apply the Pack Availability Guard for pack-based skills.
+
+## 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/uat-{topic}.html`.
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.

package/packs/product-testing/codex/uat/archive/v0.0/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: uat
+description: Create user acceptance test journeys from a target user's perspective, with role-based scenarios, acceptance criteria, and evidence capture
+type: analysis
+version: v0.0
+argument-hint: "[--variant-evaluation] [optional: persona, feature, release, journey, app, or variation spec]"
+---
+
+## 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>` 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.
+
+# UAT
+
+Invoke as `$uat`.
+
+Create a user acceptance testing plan from the perspective of a potential or target user. This skill reads the product surface, specs, journeys, stories, roadmap, and relevant research, then produces realistic end-to-end user journeys that validate whether the product satisfies user goals.
+
+UAT is not dogfooding. Dogfood asks how the app owner can adopt the product into their own workflow to understand and evaluate it. UAT asks whether a target user can complete meaningful real-world journeys and would accept the product as fit for use.
+
+This is a human-run acceptance plan, not automated testing. Do not start servers, drive browsers, call APIs, create accounts, or perform the scenarios yourself.
+
+When invoked with `--variant-evaluation` (or when the user asks to test/review UI variants), create a hands-on evaluation plan for built UX/UI variants before `$consolidate-variations`. This mode helps the user try each variant in a comparable way and capture enough evidence to form a defensible consolidation opinion.
+
+## Workflow
+
+1. **Resolve project context**
+   - Read `.agents/project.json` if it exists.
+   - Use `project_type` and `enabled_packs` when present.
+   - If project metadata is missing, infer the project type from repo signals:
+     - business-app: SaaS, marketplace, productivity, workflow, enterprise, or user-facing app
+     - devtool: SDK, CLI, API, library, infrastructure, docs, examples, or package-first developer workflow
+     - game: game engine files, playable prototypes, store assets, or game-specific README/spec language
+     - generic: no strong domain signal
+   - Read `README.md`, `AGENTS.md`, `CLAUDE.md`, relevant `docs/`, `specs/`, `spec.md`, and `tasks/` files when present.
+
+2. **Load user evidence**
+   - Business app: read `research/icp.md`, `research/journey-map.md`, `research/customer-feedback.md`, `research/metrics.md`, and `research/mvp-gap.md` when present.
+   - Devtool: read `research/devtool-user-map.md`, `research/devtool-dx-journey.md`, `research/devtool-integration-map.md`, docs, examples, and package manifests when present.
+   - Game: read `research/game-audience.md`, `research/game-fantasy.md`, `research/game-core-loop.md`, `research/game-prototype-test.md`, and `research/game-playtest-metrics.md` when present.
+   - Generic: use specs, README, routes, tests, examples, issue descriptions, and task acceptance criteria.
+   - In monorepos with `research/{app}/` or `specs/{app}/`, produce app-scoped UAT journeys for the requested app. If no app is specified and multiple apps are plausible, ask the user to choose.
+
+2b. **Variant evaluation mode**
+   - Trigger this branch when invoked with `--variant-evaluation`, when `specs/ui-layout-variations-*.md` exists for the requested topic, or when the user asks how to test/review built variants.
+   - Read `specs/ui-layout-variations-[topic].md`, `specs/ux-variations-[topic].md`, `specs/ui-requirements-[topic].md`, built variant routes/components, and any existing `research/uat-variant-evaluation-[topic].md`.
+   - Identify each variant, its intended thesis, implementation location, and the target user task it should support.
+   - Create comparable journeys that make the user perform the same core task in every variant, then capture variant-specific strengths, friction, confidence, and rejection signals.
+   - Include a side-by-side comparison matrix and a "Ready for `$consolidate-variations`?" checklist.
+   - Human execution still belongs in `tasks/manual-todo.md`; this skill writes the plan and manual tasks, but does not run the variants.
+   - After writing files, recommend `$consolidate-variations` only as the next step after the manual evaluation tasks are completed or when the user explicitly says they have already evaluated the variants.
+   - Stop after this branch. Do not generate generic target-user acceptance journeys unless the user also requested them.
+
+3. **Define acceptance perspective**
+   - Identify 1-3 target user personas or roles from the evidence.
+   - For each selected persona, define the job-to-be-done, context, goal, constraints, and acceptance threshold.
+   - Prefer external target users, buyers, evaluators, administrators, developers, or players over the product owner unless the owner is also the target user.
+   - If the target user is unclear, stop and recommend `$spec-interview`, `$journey-map`, or the relevant pack research skill. For `$journey-map` and other pack-based skills, apply the Pack Availability Guard — if the target skill's pack is not in `.agents/project.json` `enabled_packs`, recommend `$pack install <pack>` before the skill.
+
+4. **Create UAT journeys**
+   - Generate 3-7 journeys unless the user requested a narrower focus.
+   - Cover at least one critical happy path, one realistic obstacle or recovery path, and one return-use or handoff path when supported by the product evidence.
+   - Each journey must include:
+     - target user
+     - user goal
+     - real-world trigger
+     - setup and preconditions
+     - end-to-end task sequence
+     - expected user-visible success state
+     - acceptance criteria
+     - non-acceptance signals
+     - evidence to capture
+     - tester notes prompt
+     - follow-up routing
+   - Use concrete product language from specs and journeys. Avoid vague instructions such as "verify the feature works."
+
+5. **Classify follow-up work**
+   - Human-run UAT journeys go in `tasks/manual-todo.md` under `## UAT Journeys`.
+   - Use `_(after: research/uat-plan.md)_` unless the journey blocks or follows a known roadmap step. If tied to a known step, use `_(blocks: Step N.X)_` or `_(after: Step N.X)_`.
+   - Do not put human-run UAT journeys in `tasks/todo.md`.
+   - Implementation or documentation fixes discovered after a completed UAT run belong in `tasks/todo.md`, but do not invent fixes before the user journey has been attempted.
+   - One-time evidence collection belongs in `tasks/record-todo.md`.
+   - Recurring release acceptance checks belong in `tasks/recurring-todo.md` only when there is a clear release cadence.
+   - If a journey needs click-by-click help for a human-only external blocker, recommend `$guide`.
+
+6. **Present findings before writing when risk is high**
+   - If source material is thin, contradictory, or missing target-user evidence, summarize the gap and ask whether to proceed with assumptions.
+   - If source material is sufficient, write the plan and task sections directly.
+
+## Deliverables
+
+- `research/uat-plan.md` - persona assumptions, journey matrix, source evidence, acceptance checklist, result log template, and follow-up guidance.
+- In variant evaluation mode: `research/uat-variant-evaluation-[topic].md` - variant inventory, task script, comparison matrix, result logs, and consolidation readiness checklist.
+- `tasks/manual-todo.md` - append or replace only the `## UAT Journeys` section.
+- `tasks/recurring-todo.md` - optional, only when recurring UAT is useful and not already tracked.
+
+If `tasks/manual-todo.md` does not exist, create it with a `# Manual Tasks - [Project Name]` title, a short note that these items require human-only action, and the UAT section. Preserve all non-UAT sections when updating an existing file.
+
+Use this journey format in `research/uat-plan.md`:
+
+```markdown
+### Journey N: [Name]
+
+- Target user: [persona or role]
+- User goal: [what the user is trying to accomplish]
+- Trigger: [real-world reason the user starts]
+- Setup: [accounts, data, environment, permissions, or sample state needed]
+- Task sequence:
+  - [step the human tester performs as the target user]
+- Expected success state: [observable user-visible result]
+- Acceptance criteria:
+  - [ ] [specific criterion]
+- Non-acceptance signals: [confusion, delay, missing affordance, incorrect result, trust issue, or blocker]
+- Evidence to capture: [screenshots, recordings, notes, timestamps, records, command output, or artifacts]
+- Tester notes prompt: [question that captures whether the target user would accept this]
+- Follow-up routing: [manual note, $spec-interview, $journey-map, $guide, or task promotion guidance]
+
+#### UAT result log
+
+- Status: Not run | Pass | Fail | Blocked
+- Evidence captured:
+- Tester notes:
+- Follow-up tasks promoted:
+```
+
+Use this variant evaluation format in `research/uat-variant-evaluation-[topic].md`:
+
+```markdown
+## Variant Evaluation Plan
+
+### Variant Inventory
+
+| Variant | Implementation location | Thesis | Primary task |
+|---|---|---|---|
+
+### Shared Evaluation Script
+
+- Target user:
+- Scenario:
+- Setup:
+- Core task sequence:
+- Success criteria:
+- Non-acceptance signals:
+- Evidence to capture:
+
+### Per-Variant Result Log
+
+#### [Variant name]
+
+- Status: Not run | Pass | Fail | Blocked
+- Evidence captured:
+- What worked:
+- What felt wrong:
+- Time/friction notes:
+- Keep for consolidation:
+- Reject for consolidation:
+- Confidence: Low | Medium | High
+
+### Side-by-Side Comparison Matrix
+
+| Dimension | Variant A | Variant B | Variant C | Current preference | Evidence |
+|---|---|---|---|---|---|
+
+### Ready for `$consolidate-variations`?
+
+- [ ] Every built variant has been tried or explicitly skipped.
+- [ ] Evidence exists for each kept/rejected design element.
+- [ ] Open blockers are documented.
+- [ ] The user has enough confidence to converge.
+```
+
+Use this item format in `tasks/manual-todo.md`:
+
+```markdown
+## UAT Journeys
+
+- [ ] Run UAT journey: [Journey name] as [target user] _(after: research/uat-plan.md)_ - capture evidence in `research/uat-plan.md`.
+```
+
+## Task Classification
+
+- Human UAT journey execution goes in `tasks/manual-todo.md`.
+- Variant evaluation tasks go in `tasks/manual-todo.md` under `## UAT Journeys` and should reference `research/uat-variant-evaluation-[topic].md`.
+- Immediate implementation or documentation fixes confirmed by completed UAT go in `tasks/todo.md`.
+- One-time condition-gated evidence collection goes in `tasks/record-todo.md`.
+- Release-cadence UAT checks go in `tasks/recurring-todo.md`.
+- Do not put non-blocking records or recurring obligations in `tasks/todo.md` unless they have been explicitly promoted into current execution work.
+
+## Constraints
+
+- Do not run or operate the product in this skill.
+- Do not start dev servers, launch browsers, use Playwright, call APIs, create accounts, or perform CLI workflows.
+- Do not mark journeys complete; only a human tester can do that after performing them.
+- Do not recommend `$consolidate-variations` before variant evaluation evidence exists, unless the user explicitly confirms they have already reviewed the variants and are ready to converge.
+- Do not duplicate existing unchecked UAT or manual tasks. Reference existing items when they already cover the same journey.
+- Prefer evidence-backed target-user journeys over exhaustive feature coverage.
+- Keep dogfood and UAT separate: use `$dogfood` for owner/operator adoption into the builder's workflow; use `$uat` for target-user acceptance journeys.
+- If no credible user journey, story, spec, or product surface can be found, stop and recommend `$spec-interview`, `$journey-map`, or the relevant pack research skill. Apply the Pack Availability Guard for pack-based skills.
+
+## Alignment Page
+
+When this skill produces durable deliverables (research, specs, plans, reports, prototypes, or any document output), build a full-depth HTML alignment page at `alignment/uat-{topic}.html`. Use a normalized topic slug derived from the app, feature, research subject, report subject, or output filename.
+
+**Full content requirement.** The alignment page must contain the complete content of every proposed markdown deliverable -- every section, every finding, every detail, every list item. It is a thorough interactive review document, not a summary. Render the full deliverable content in clean, readable HTML with appropriate hierarchy, styling, and navigation. If the skill writes multiple scoped deliverables in one run, build one alignment page that contains all deliverables with anchor-linked navigation. Durable tracker artifacts, such as `research/assumption-tracker.md`, remain canonical markdown outputs but must also be fully rendered into the alignment page before approval.
+
+**Dark-mode styling.** Use a dark color scheme by default. Base CSS variables: `--bg: #0d1117; --surface: #161b22; --border: #30363d; --text: #c9d1d9; --text-muted: #8b949e; --accent: #58a6ff; --green: #3fb950; --red: #f85149; --orange: #d29922; --purple: #bc8cff;`. Apply `background: var(--bg); color: var(--text);` on body. Use `--surface` for cards, nav, and table headers. Use `--border` for all borders. Use `--purple` for question blocks and gate headings. Use `--accent` for links and section headings. Keep headings `color: #fff` or `var(--accent)` for hierarchy. Question block backgrounds should use `#1c2333`.
+
+**Alignment gates.** Treat gates as explicit review sections inside the HTML page. A gate blocks finalization until its required inline questions are answered and compiled into YAML. Include every gate that applies to the skill output, and include these gate types whenever relevant: evidence coverage, assumptions/confidence, scope/non-goals, candidate/verdict decisions, artifact destination, proposed file changes, coverage checkpoint, and post-approval route.
+
+**Report-only research gates.** For report-only or pre-approval research skills, the alignment page must explicitly contain evidence coverage, assumptions/confidence, recommended path, proposed file changes, and approval gates before any canonical research, spec, or task file is created or updated.
+
+**UAT-specific gates.** Render journey coverage, participant or evaluator assumptions, acceptance verdicts, evidence gaps, artifact destination, proposed file changes, and post-approval route as gates.
+
+
+**Required inline questions.** Each gate must contain at least one required inline question placed directly under the content it governs, inside a visually distinct question block. Each question must use radio-button inputs and include two standing options after the skill-generated choices: "Other / None of the above" backed by a multi-line text box for free-form input, and "Need clarification" backed by an optional notes box where the user can explain what is unclear. When any radio option other than "Other" or "Need clarification" is selected, show an optional "Additional notes" text box beneath it so the user can qualify their choice. Generate questions based on what genuinely needs user input -- do not add filler questions. Do not create a separate bottom "Decisions & Clarifications" section.
+
+**Gate YAML contract.** At the bottom of the page, include a "Compile Answers" button that aggregates answers from all inline gate questions throughout the page, including free-text notes. The button remains disabled until every required question has a selection, shows a count of remaining unanswered questions, and scrolls to the first unanswered question if clicked early. When every question is answered, generate a structured YAML block with one item per gate answer using this stable shape: `section`, `gate_type`, `status` (`answered`, `other`, or `needs-clarification`), `answer`, optional `notes`, and optional `target_artifact` or `target_path` when the gate controls file output. After successful compilation, automatically attempt to copy the YAML to the clipboard with the Clipboard API, display copy status, and display the YAML in a read-only textarea with an explicit "Copy YAML" button. The copy button must retry clipboard copy when supported and fall back to selecting the textarea contents when clipboard access is unavailable or blocked.
+
+**Pre-approval stop.** Before user approval, the next action is review of the HTML alignment page, not downstream routing. Ask the user to review the page and provide the compiled YAML answers. Do not include `Recommended next skill`, `Recommended next command`, or downstream routing language until after compiled YAML has been provided and the approved artifacts have been written or updated.
+
+**Diff highlighting on updates.** When the agent updates an existing alignment page after receiving compiled answers, highlight what changed since the previous version. The agent chooses inline annotation or side-by-side layout per situation.
+
+**Archiving.** Before replacing an existing alignment page, archive it to `docs/history/archive/YYYY-MM-DD/HHMMSS/alignment/uat-{topic}.html`.
+
+**Browser open.** Attempt to open the resulting HTML page in the browser and report whether the open succeeded or was blocked. A blocked browser-open attempt does not make the skill fail when the files were written correctly.
+
+## 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.
+
+## Default Shipping Contract
+
+- **Default next-step routing:** when reporting completion, include either `Recommended next skill: <command>` or the two-line pair `**Next work:** <specific task or "none">` and `**Recommended next command:** <one command or route>` so the next operator has a concrete handoff.
+- If this skill creates or modifies tracked repository files, finish by committing and pushing all intended changes to the repository primary branch (`main` when present, otherwise `master`) before stopping, even if the user did not explicitly ask for commit/push.
+- Do not leave tracked changes or unpushed commits behind. If unrelated tracked work is already present, either include it in sensible commits too or stop and explain the blocker.
+- This contract does not override stricter safety rules about secrets, destructive history changes, release publication/tag confirmation, or production deploy confirmation.