Prd UX Design

PRD + Scenario Design

When to use this skill

Use this skill when the task is to clarify or change product intent before engineering work begins:

• A PM or designer wants to add or update a PRD.
• A GitHub Issue, ADO Work Item, or chat request changes user-facing behavior.
• A VS Code, CLI, or cross-surface scenario needs design before specs.
• An engineering workflow finds missing, ambiguous, or unapproved PRD/scenario input.

Do not use this skill for specs, tests, code, or implementation. Handoff to engineering only after PRD + scenario artifacts are approved or explicitly confirmed as unchanged.

Source locations

PRDs are high-level product documents. Scenarios split PRD intent into concrete flows such as creating, testing, or provisioning a DA. Scenario Markdown, including inline Mermaid, is the AI-primary source for experience behavior and later CLI E2E / VS Code UI test intent. HTML helps humans, AI agents, and engineering review layout, navigation, and visual states, but they must not derive specs, AC rows, tests, or behavior contracts from HTML alone.

Scenario HTML format, region structure, shared flow components, collapsible-section contract, and card-kind vocabulary are defined in docs/01-product/scenarios/README.md. Follow it as the source of truth — do not duplicate the rules here, and do not invent per-page CSS, scripts, or markup that re-implement behavior the shared scenario components already provide. If a new shared behavior is needed, extend docs/01-product/_assets/scenario-components/ so every scenario benefits, rather than forking it inline in one page.

The active docs/01-product/prd/ tree is intentionally Markdown-only. Do not put scenario flow blocks, HTML visual aids, or PRD-local navigation HTML under prd/; place scenario artifacts under docs/01-product/scenarios/ and link them back to PRD requirement IDs.

The product root docs/01-product/README.md is the AI-facing source/context for this workspace. The scenario directory guide docs/01-product/scenarios/README.md is the only README under docs/01-product/scenarios/ and defines the required group classification, Markdown format, and HTML format for scenario artifacts. The only active index-named HTML under this workspace is docs/01-product/scenarios/index.html, and it links only to human-readable scenario HTML pages.

Documents under docs/01-product/_backups_/ are not active product contracts. Use them only as source material, and rewrite content into the current PRD or scenario schema before handoff.

Workflow

Phase 1 — Intake

Start from the concrete request: PM chat, GitHub Issue, ADO Work Item, or existing PRD/scenario page.

1. Clarify the user's need, trigger, affected persona, expected outcome, and requested review owner.
2. Inspect current PRDs and scenario groups to decide whether the request is already covered, needs a PRD update, needs a scenario update, or needs both.
3. Classify the change: new PRD, PRD update, new scenario, scenario update, or no product design change needed.
4. Identify PM owner, Engineer owner, affected persona, capability/domain, the workload group defined by the scenario guide, and user surface (VS Code, CLI, both, or neither). Use docs/01-product/owner.md as the owner lookup, and cross-check package-level engineering owners with .github/CODEOWNERS when useful.
5. Read nearby product context: PRD pages, personas, capabilities, relevant scenarios, architecture constraints, and infrastructure constraints.

Phase 2 — Ask before guessing

This mirrors Global behavioral principle #1 in .github/copilot-instructions.md: if the requirement, owner, success criteria, or user flow is unclear, stop and ask specific questions.

• GitHub Issue / ADO: comment with concrete questions and @owner.
• Chat: ask the user directly.
• Do not write specs, tests, or code while product or scenario ambiguity remains.

Good questions are answerable and scoped:

• "Is this flow required in VS Code, CLI, or both?"
• "What is the success state the user must see?"
• "Is this error recoverable in the same flow or does the user restart?"
• "Which persona owns the decision: developer, IT admin, or both?"
• "Who is the PM owner and who is the Engineer owner for this PRD?"

Phase 3 — Draft PRD changes

Create or update Markdown under docs/01-product/prd/. Keep the PRD high-level, concise, and traceable:

# <Capability or scenario name>

## Metadata

- Status: draft | review | approved | implemented | superseded | archived
- Created: YYYY-MM-DDTHH:mm:ssZ
- Last updated: YYYY-MM-DDTHH:mm:ssZ
- PM owner: <owner-id or @handle from ../owner.md>
- Engineer owner: <owner-id or @handle from ../owner.md>
- Owner source: ../owner.md
- Related request: <GitHub issue, ADO work item, or chat summary>

## Problem

Who has the problem and why it matters.

## Goals

Measurable outcomes the change must enable.

## Non-goals

What this change intentionally does not solve.

## Users and scenario map

Personas, entry points, and links to concrete scenario flows under `../scenarios/<group>/`.

## Requirements

ID-based product requirements (`REQ-01`, `REQ-02`, ...).

## Success metrics

How PM/humans judge the change after release.

## Constraints and risks

Architecture, infrastructure, compliance, platform, or rollout limits.

## Open questions

Unresolved items that block scenario design, specs, or implementation.

Metadata rules:

• Created and Last updated use ISO 8601 UTC timestamps. If exact time is unavailable, use the current date with T00:00:00Z.
• Update Last updated whenever the PRD content or status changes.
• PM owner and Engineer owner must resolve to a human or team in ../owner.md, or to a GitHub handle. Do not approve a PRD with TBD owners.
• Status tracks the PRD document lifecycle, not test or code state.
• implemented means the approved PRD has been delivered by the applicable engineering workflow; use superseded or archived when the product direction is no longer current.

Phase 4 — Draft scenario changes

Create or update canonical Markdown under docs/01-product/scenarios/<group>/<scenario-slug>.md, or use scenario:init --proposal <proposal-key> for a sibling redesign. Keep scenario narrative, flow Mermaid, surface notes, state notes, and validation intent in that one Markdown file.

Before drafting, apply the Scenario model and legality gates:

1. Classify the requested artifact as a journey map, a product scenario, or validation intent using the product-owned definitions.
2. Complete the required scenario content and collect the evidence named by the product-owned legality gate.
3. Leave missing evidence as an open question and stop before approval or engineering handoff.

Complete the product-owned Markdown format, including its required metadata, user-visible outputs, flow, and validation notes. Do not maintain a second scenario-format checklist in this skill.

Generated visual/state reference:

• Run npm run scenario:render from packages/fx-core; do not author or patch same-basename HTML manually.
• Review the HTML projection for flow, shared components, current v4 prompt metadata, and Mermaid output, but resolve behavior errors in Markdown or v4 declarations.
• Run npm run scenario:check before handoff so generated HTML and index bytes are current.

Phase 4a — Scenario lifecycle (redesign of a live scenario)

When a shipped scenario needs to change because of a new feature, do not edit the current contract in place. Create a metadata-declared sibling proposal so reviewers can compare it against shipped behavior.

Lifecycle comes only from Status: approved and implemented are Current; draft and review are In review; archived and superseded are hidden. Directories do not assign state. Existing draft/ files are migration inputs only and produce a tooling warning.

The stable SCN-<ID> is preserved across draft, live, and archive. The same flow keeps the same scenario ID across redesigns.

Lifecycle metadata fields used in addition to the standard scenario metadata:

Open a proposal

Trigger: a shipped scenario needs to change because of a new feature.

1. Run npm run scenario:init -- --group <group> --slug <slug> ... --timestamp <ISO-8601-UTC> --proposal <proposal-key> --redesign-trigger <reason> from packages/fx-core.
2. Preserve the canonical Scenario ID, set Status: draft, and link Supersedes to the current contract.
3. Leave the current Markdown unchanged; it remains authoritative for shipped code.
4. Run scenario:render; metadata adds the proposal to In review automatically.

Iterate in the proposal

• Treat the current live <group>/<slug>.{md,html} as the design baseline. Before editing the draft, re-read the live Markdown and HTML in full and reuse its scenario narrative, shared components, card layout, naming conventions, and state structure. The draft should read as a delta on top of live, not a parallel rewrite.
• Carry over anything that is not being explicitly redesigned: card titles, ordering, copy, asset choices, Mermaid node names, and engine-faithful snippets. Only diverge where the redesign actually requires it, and call out each divergence in the draft narrative or Redesign trigger: note so reviewers can diff against live.
• Cross-check sibling drafts in the same group for consistency (for example, a create-* draft and an add-* draft should share naming, env var, and file-shape conventions). When the redesign changes a convention, apply it to every affected draft in the same PR.
• All authored redesign changes happen inside <slug>--<proposal-key>.md; HTML and index changes come only from scenario:render.
• Set Status: review when ready for review. Standard Phase 5 approval applies, and scenario:accept records only reviewed implementation fingerprints.
• The proposal is not the shipped behavior contract. UI and E2E tests for shipped behavior still derive from the current contract until promotion.

Promote a proposal

Trigger: the proposal is approved and the implementing change is ready to ship.

1. Rename the old canonical Markdown to a unique historical name without a -- proposal suffix, for example <slug>-superseded-<YYYYMMDD>.md. Set Status: superseded, set its same-basename Visual/state reference, and set Supersedes: <slug>.md to identify the new canonical successor.
2. Move the accepted proposal Markdown to <group>/<slug>.md, remove Proposal key, Supersedes, and Redesign trigger, set its Visual/state reference: <slug>.html, set Status: approved or implemented, and refresh Last updated.
3. Run scenario:render and scenario:check. Render creates the renamed historical projection and removes obsolete proposal HTML only when it carries the generated-file marker; do not move or edit HTML manually.

Discard a proposal

If the redesign is abandoned, delete its sibling Markdown and rerun scenario:render. Render removes the corresponding generated-marker HTML; the current contract and any manual HTML remain untouched.

Phase 4.5 — Update the human-facing product index

When scenario Markdown or scaffold presentation metadata changes, run scenario:render to update docs/01-product/scenarios/index.html and same-basename HTML.

The index is for human navigation and review. It should:

• Split entries from metadata into Current (approved, implemented) and In review (draft, review).
• Do not list archived or superseded artifacts.
• Do not link README files, PRD Markdown, scenario Markdown, backups, or renderer/tooling HTML.
• Label artifact type (HTML) clearly.
• Preserve the source distinction: Markdown is the AI-primary behavior source; linked HTML is visual/state reference.
• Exclude renderer/tooling HTML from product artifact navigation.
• Avoid becoming the source of product behavior; behavior remains in Markdown.

Phase 5 — Human approval gate

Before handoff, summarize the product design delta:

• PRD files changed or confirmed unchanged.
• Scenario files changed or confirmed unchanged, including group path.
• PRD metadata includes status, timestamps, PM owner, and Engineer owner.
• Product root index changed or confirmed unchanged.
• Product artifact renderer changed or confirmed unchanged when preview behavior changes.
• Open questions resolved or still blocking.
• Whether specs and implementation should proceed.

Ask for approval from the human owner. If approval is not available, stop with the open questions and do not hand off to implementation.

Rendered review links in the PR body

When opening (or updating) a PR that touches scenario HTML under docs/01-product/scenarios/, include side-by-side rendered diff links in the PR body so reviewers can read the design without cloning. Follow docs/01-product/_assets/scenario-diff-viewer/README.md for the URL template — do not duplicate it here.

• One link per scenario HTML changed in the PR (or per draft pair, when a draft is in flight).
• Pick the case from the viewer README: Evolving draft (base ref vs PR HEAD) when the file already existed on the base branch; Brand-new draft (live sibling vs draft) when the draft file is new in this PR.
• Pin both sides to immutable refs. Use the PR HEAD commit SHA for the new side, and either the base commit SHA or a tag for the baseline side. Never pin a review link to dev, main, or the PR branch name — those move and silently change the diff later.
• Both the viewer page itself and any side that lives only on the PR branch must be served from the PR HEAD SHA (the viewer is committed under _assets/).
• Note in the PR body that raw.githack shows an External Content Notice on first visit per browser, and the reviewer must click Open the page once.
• If a scenario HTML is brand-new and has no live sibling and no draft pair to diff against, link the standalone raw.githack preview pinned to the PR HEAD SHA instead of forcing a diff link.

Phase 6 — Handoff to engineering

When approved, produce a short handoff packet:

## PRD/scenario handoff

- Source request: <issue/chat/ADO link or summary>
- PRD artifacts: <links>
- Scenario artifacts: <links including scenario group>
- Scenario IDs: SCN-...
- Human review index: docs/01-product/scenarios/index.html
- PM owner: <owner-id or @handle>
- Engineer owner: <owner-id or @handle>
- PRD status: draft / review / approved / implemented / superseded / archived
- Requirement IDs: REQ-...
- Surfaces: VS Code / CLI / both
- Deferred validation: L2 CLI E2E scenarios, L3 VS Code UI scenarios
- Open questions: none / listed blockers
- Next step: engineering implementation workflow, or listed blocker if not ready

Only after this handoff should the engineering workflow generate or update specs, AC tables, tests, and code.

Quality bar

• PRD states why, who, scope, non-goals, measurable success, constraints, and open questions.
• PRD metadata includes ISO 8601 Created and Last updated timestamps, PM owner, Engineer owner, owner source, related request, and status.
• PRD owners are resolvable through docs/01-product/owner.md, .github/CODEOWNERS, or explicit human handles; TBD owners block approval.
• Scenario Markdown records behavior and state transitions, not just visuals.
• New or materially changed scenarios satisfy the linked product-owned Scenario model, classification, and legality rules.
• Markdown with inline Mermaid must be sufficient for an AI agent to understand behavior; HTML supplements visual structure and states when present.
• HTML, when present, is concise visual/state reference and cannot be the only source of behavior.
• The product root index links to newly added or renamed human-readable scenario HTML pages only.
• Every unresolved ambiguity is either answered by a human or listed as a blocker.
• No specs, tests, or implementation are changed by this skill unless the user explicitly pivots to the applicable engineering workflow.

Common mistakes

Last todo of every PRD/scenario turn

For every scenario Markdown or bound v4 declaration changed in this turn, scenario:render has regenerated HTML and index data, and scenario:check has passed without errors.