Menu
Use when adding or changing product requirements, scenarios, user flows, surface behavior, or design artifacts before specs or implementation.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Builds, tests, and deploys Microsoft 365 apps and agents for Teams and Copilot. Includes sub-skills for project creation, local testing, cloud deployment, troubleshooting, and Slack-to-Teams migration. USE FOR: Teams agent, bot, tab, message extension, Declarative Agents, Custom Engine Agents, local testing, Agents Playground, Azure resource provision, remote deployment, Slack to Teams migration, cross-platform bot development, Block Kit to Adaptive Cards conversion. DO NOT USE FOR: general web development, non-bot/non-Teams projects.
Use when: reading a docs scenario, PRD, mockup, or user flow and using vscuse-ui/noVNC as the primary authoring surface to record, generate, replace, or update vscuse test plans; decide existing coverage vs new case; validate product behavior against docs, then finish with vscuse CLI validation.
Use when: setting up shared local vscuse prerequisites, credentials, runner, local or pinned published Docker images, local VSIX, env variables, and common rules for Microsoft 365 Agents Toolkit vscuse work. Use vscuse-case-diagnosis for running/fixing existing cases; use vscuse-scenario-authoring for docs/mockup-driven recording and plan generation.
Use when: running an existing vscuse test case, reproducing a failing vscuse plan, deciding product bug vs test plan drift vs setup failure vs flake, repairing a failing case with vscuse-ui/noVNC when useful, and finishing with vscuse CLI validation.
End-to-end workflow for agent-driven changes that add or modify behavior in the toolkit packages. Use when: adding or changing a behavior (anything that warrants an Acceptance Criteria row); refactoring toward a structural shape governed by ADRs in `docs/02-architecture/`; changing v4 scaffolding architecture, removing duplicate Q1/Q2/Q3 logic, extracting shared engines, or moving logic into providers/validators/steps; adding a behavior-changing CLI or VS Code action. Codifies the design-first → tests-from-AC → implement → verify → self-review → docs-when-needed cycle that keeps contributions safe to merge.
Greets the user with a fun fact about declarative agents and Microsoft 365 Copilot.
| name | prd-ux-design |
| description | Use when adding or changing product requirements, scenarios, user flows, surface behavior, or design artifacts before specs or implementation. |
| argument-hint | Describe the issue, product request, scenario change, or design question |
Use this skill when the task is to clarify or change product intent before engineering work begins:
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.
| Artifact | Location | Role |
|---|---|---|
| PRD pages and requirement deltas | docs/01-product/prd/ | Markdown-only product intent: problem, users, scope, success criteria, constraints |
| Scenario directory guide | docs/01-product/scenarios/README.md | Format rules for AI-readable scenario Markdown and human-readable scenario HTML |
| Scenario HTML components | docs/01-product/_assets/scenario-components/ | Reusable VS Code-style static flow components and icon assets for scenario HTML |
| Scenario Markdown | docs/01-product/scenarios/<group>/<scenario-slug>.md | Concrete user flow: steps, states, edge cases, per-surface notes, inline Mermaid flow, and CLI E2E / VS Code UI test intent |
| Owner registry | docs/01-product/owner.md | PM and Engineer owner lookup for PRD metadata |
| Mermaid flows | Inline Mermaid inside the owning scenario Markdown | AI-primary flow source embedded in the scenario contract |
| HTML artifacts | docs/01-product/scenarios/<group>/<scenario-slug>.html with the same basename as the owning Markdown when needed | Visual/state reference for humans, AI agents, and engineering; should concretize the Markdown flow and render the Mermaid reference from the owning Markdown; not the behavior source |
| Scenario proposals | docs/01-product/scenarios/<group>/<scenario-slug>--<proposal-key>.md | Metadata-declared in-review redesign; same Scenario ID as its canonical contract |
| Generated scenario HTML | Same-basename .html produced by scenario:render | Deterministic review projection; never a behavior source or hand-authored artifact |
| Product review stylesheet | docs/01-product/_assets/product-review/product-review.css | Shared page-level styles for product index and scenario HTML; not a behavior source |
| Product review index | docs/01-product/scenarios/index.html | Human-facing locator for scenario HTML pages under docs/01-product/scenarios/; do not list README or Markdown source files |
| Product artifact renderer | docs/01-product/_assets/product-artifact-viewer/index.html | Tooling-only renderer for Markdown artifacts; not a product artifact |
| Backups | docs/01-product/_backups_/ | Pre-reorganization source material; not active PRD/scenario contract |
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.
Start from the concrete request: PM chat, GitHub Issue, ADO Work Item, or existing PRD/scenario page.
new PRD, PRD update, new scenario, scenario update, or no product design change needed.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.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.
@owner.Good questions are answerable and scoped:
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.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.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:
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:
npm run scenario:render from packages/fx-core; do not author or patch same-basename HTML manually.npm run scenario:check before handoff so generated HTML and index bytes are current.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:
| Field | Appears in | Purpose |
|---|---|---|
Proposal key: | Sibling proposal | Stable suffix used in <slug>--<proposal-key>.md. |
Supersedes: | Proposal or historical contract | Path to the contract this version proposes to replace or replaced. |
Redesign trigger: | Sibling proposal | One-line reason: GitHub issue, ADO work item, or feature name. |
Trigger: a shipped scenario needs to change because of a new feature.
npm run scenario:init -- --group <group> --slug <slug> ... --timestamp <ISO-8601-UTC> --proposal <proposal-key> --redesign-trigger <reason> from packages/fx-core.Status: draft, and link Supersedes to the current contract.scenario:render; metadata adds the proposal to In review automatically.<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.Redesign trigger: note so reviewers can diff against live.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.<slug>--<proposal-key>.md; HTML and index changes come only from scenario:render.Status: review when ready for review. Standard Phase 5 approval applies, and scenario:accept records only reviewed implementation fingerprints.Trigger: the proposal is approved and the implementing change is ready to ship.
-- 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.<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.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.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.
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:
approved, implemented) and In review (draft, review).archived or superseded artifacts.HTML) clearly.Before handoff, summarize the product design delta:
Ask for approval from the human owner. If approval is not available, stop with the open questions and do not hand off to implementation.
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.
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.dev, main, or the PR branch name — those move and silently change the diff later._assets/).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.
Created and Last updated timestamps, PM owner, Engineer owner, owner source, related request, and status.docs/01-product/owner.md, .github/CODEOWNERS, or explicit human handles; TBD owners block approval.| Mistake | Fix |
|---|---|
| Writing implementation details into PRD | Keep PRD at problem, scope, requirements, and success criteria; defer mechanics to specs. |
| Treating an HTML mock as the scenario contract | Move behavior into scenario Markdown with inline Mermaid; keep HTML as concise visual/state reference. |
Re-implementing scenario HTML presentation per page (inline styles, ad-hoc <details> wrappers, hand-written badges, custom card markup) | Author scenario HTML per docs/01-product/scenarios/README.md using the shared scenario components and the documented region/card structure. Extend the shared components if something is missing. |
| Forgetting the product index | Run scenario:render; never hand-maintain artifact arrays. |
| Leaving PRD owners as TBD | Resolve PM and Engineer owners through owner.md, CODEOWNERS, or a direct human answer before approval. |
| Forgetting metadata timestamps | Update Last updated and status whenever the PRD changes. |
Treating _backups_ as active source | Rewrite backup content into the current PRD or scenario schema before using it for handoff. |
| Skipping owner questions because the flow seems obvious | Ask the owner; ambiguous scenario design creates bad AC rows later. |
| Letting PRD/scenario work drift into code | Stop after approval and hand off to the applicable engineering workflow. |
| Creating AC rows in PRD | Use PRD requirement IDs; AC rows belong in operation specs. |
| Editing a current scenario in place when a new feature redesigns its flow | Create a <slug>--<proposal-key>.md sibling with Status: draft (Phase 4a). |
| Drafting a redesign without re-reading the current live scenario | Read live <group>/<slug>.{md,html} first and reuse its narrative, components, copy, and conventions; the draft should be a diff on top of live, not a parallel rewrite. |
| Letting sibling drafts in the same group drift from each other | Cross-check related drafts (for example create-* vs add-*) and apply convention changes consistently in the same PR. |
| Describing UI flow without listing user-visible outputs | Add a ## User-visible outputs section that enumerates every file change, notification, error/recovery message, env/secret write, and external side effect the scenario produces. Without it, reviewers can't tell what the user actually ends up with. |
| Enumerating every template boilerplate file in a scaffolding scenario | List only runtime-modified outputs (driven by user answers, drivers, or conditional logic) in detail; collapse stock template boilerplate into a single "plus the standard template files" line. |
| Naming a file in an earlier step but not saying where later steps write into it | In the User-visible outputs section, link each file entry back to the step that picks/names it, and identify the specific keys/blocks that get written there. |
| Promoting a proposal without preserving the previous current contract | Keep the previous Markdown as a uniquely named archived or superseded sibling, then render generated artifacts. |
| Editing generated HTML or index arrays | Change Markdown/status or v4 declarations, then run scenario:render. |
Listing historical HTML in docs/01-product/scenarios/index.html | Let generated metadata classification hide archived and superseded artifacts. |
| Opening a scenario-touching PR without rendered review links | Add side-by-side diff links to the PR body per docs/01-product/_assets/scenario-diff-viewer/README.md, one per changed scenario HTML or draft pair. |
Pinning the rendered review link to a branch name (dev, main, the PR branch) | Pin both sides to immutable refs — the PR HEAD commit SHA for the new side, and a commit SHA or tag for the baseline — so the diff stays stable as branches advance. |
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.