prd-writing

PRD Writing

Goal

Create outputs/<run-id>/prd.md as a product document that starts from users and their problems, then makes every proposed behavior reviewable through a requirement list and matching requirement details.

Workflow

1. Load artifacts/prd-contract.md. Use its canonical ordered structure only for a new PRD. When a new PRD migrates or references another PRD, the source supplies only confirmed requirement content, terminology, assets, and explicitly requested migration boundaries; it never supplies the new document's chapters, field labels, numbering, or canonical structure unless the user explicitly says so. Do not record an assumption that the new PRD follows the source PRD's structure. For an in-place revision, the identified PRD is the sole structural source of truth: preserve its existing chapter order, headings, fields, numbering, and unaffected content. Do not use another or older PRD, or the canonical new-document structure, to normalize its overall structure unless the user explicitly requests a structural rewrite. Apply only the user-requested patch; when that patch concerns screenshots, it is limited to the matching 需求详情 cell. Remove deleted requirements and renumber the remaining detail IDs consecutively only when the user requested a requirement deletion.
2. Identify target users, their scenario, problem, desired outcome, and the source or confirmation status before drafting requirements.
3. For a new PRD, apply the evidence boundary and requirement-granularity rules in artifacts/prd-contract.md before creating 需求清单. Create 需求清单 before 需求详情; use the matching detail number, such as 5.1, as the sole identifier for every coherent user need, and do not use a visual state or coverage decision as a requirement boundary. For an in-place revision, preserve existing requirement boundaries and identifiers unless the user explicitly changes them.
4. Expand each requirement only in its matching 需求详情 subsection. Do not create requirements that cannot be traced back to a user problem or scenario.
5. For a new standard PRD, structure each requirement detail with the four required rows: 用户与场景, 需求入口, 需求详情, and 设计与交互. For a layout-only revision, do not add, delete, rename, or reorder rows. Keep every screenshot and its matching state logic inside the existing single 需求详情 cell as repeated prd-detail-media blocks: fixed-width image column on the left and that state's functional logic on the right. The right column is not a filename, caption, or generic annotation such as “对应成功状态”; it must state the user-visible rule, boundary, or feedback shown by the adjacent image. Do not add a separate 图示 row or visible image-name caption. For an implemented-feature PRD, create a coverage item for every independently reviewable production user-facing state retained in the PRD: real_figure, required_placeholder, or not_required, with rationale. A named production user-facing page, panel, dialog, node, toolbar, media state, or flow requires visual evidence; do not mark it not_required. Coverage items are visual evidence, not requirement items. Do not combine several states into one coverage item or placeholder name. Add each required figure or placeholder inline with its matching requirement. Before required_placeholder, execute and record the capability chain: discover existing previews, reuse or activate the project runtime using its actual project configuration, recover the target test state, then attempt Playwright, Chrome DevTools, and Computer Use. Do not assume or require a fixed port, and do not use skipped as a capture result. Every attempted capability and capture records action、evidence and a non-empty local result_ref under tool-results/. When capture recovery fails, continue with required_placeholder, set the PRD status to 可评审（图示待人工补全）, and record the named manual replacement instruction in run-log.yaml; do not label the PRD as degraded or block its review. A placeholder cell contains only controlled 占位图：功能-状态.png values, separated by <br> when several states need placeholders. User-provided videos are not screenshots: preserve the original local video as an inline player with browser controls; never replace a supplied video with a still frame unless the user explicitly asks for a frame image. Put normal and exception states, permissions, empty/loading/error feedback, recovery, and boundaries in 需求详情; when it has two or more rules, split independently presented concerns into content groups. Restart every group's heading at 一、; restart that group's rules at 1.、2.、3.. Never continue a previous group's 二、/三、 numbering just because the groups share one 需求详情 cell. Write each heading and numbered rule on its own <br> line, and separate adjacent groups with one <br>. A media block or content group is not a new 5.x requirement. Do not add risk, pending-confirmation, acceptance-result, technical-test, or standalone exception fields.
6. Use 用户流程图 for a user's cross-surface or cross-state interaction path and 操作流程图 for operation rules, conditions, permissions, state transitions, or exceptions. Neither is mandatory: add either or both Mermaid diagrams immediately above the matching detail table only when they improve reviewability; when both are present, list the user flow first.
7. Treat a screenshot as evidence, not decoration. Follow the canonical visual-evidence, crop, placeholder, and fixed-column media-block rules in artifacts/prd-contract.md; this workflow must not restate or override them. Record the required visual-capture review only in internal evidence. If a figure does not improve reviewability, omit the media block.
8. Add 需求调研, 多语言需求, and 埋点需求 only when they have real, decision-relevant content. Before omitting 多语言需求 or 埋点需求, complete the per-requirement coverage review in run-log.yaml: not_needed requires evidence that the requirement has no changed visible copy or no decision-relevant measurable action/outcome. Record measurable actions and outcomes as real YAML lists, never comments. The absence of existing event code or event definitions is not evidence for omission. For every research row, state the source fact and the PRD decision it changes. In a Chinese PRD, the multilingual pure-text block and 文案 column contain the localized Chinese copy only, not an English source string. A multilingual section contains only new or changed user-visible copy in one copyable pure-text block, followed by 文案、使用位置、参数 rows; apply the PRD contract's smallest-localizable-copy-unit rule so every independently usable string has its own pure-text line and matching 文案 row. List placeholders such as {reason} in 参数 and use / when none exist. A tracking table uses only 事件、事件名称、上报时机、附加参数、备注: use unique lowercase semantic feature_action identifiers such as login_click, never PRD-location or generic IDs such as prd_5_1_view or journey_view. Select access events, meaningful clicks/operations, important outcomes, and value signals such as duration, depth, exposure, completion, or retention when the user journey needs them. Keep 上报时机 to one observable sentence, put only event-external properties in 附加参数, and use / when either 附加参数 or 备注 has no content. Omit empty optional sections and explanatory labels.
9. Clean user input before writing: retain user-confirmed facts, source-backed observations, and explicit product decisions; remove template guidance, process narration, technical evidence, duplicated explanation, and vague filler. If an unresolved product rule materially affects the requirement, ask for a decision before generation; do not put it in the PRD. Never invent behavior from model intuition.
10. Add a version record only for the initial document or a material change to a user need, product behavior, scope, rule, or user-visible copy. Do not record rendering, formatting, validation, synchronization, or other document operations.
11. For implemented-feature reconstruction, use technical evidence only to infer and verify user-visible behavior. Record technical evidence in run-log.yaml, never in the PRD.
12. Do not include technical implementation or solution content in a PRD, including code paths, routes, components, services, APIs, schemas, infrastructure, commands, technical architecture, CSS variables or selectors, color tokens, gradients, stacking levels, exact dimensions, or source field names. Translate implementation evidence into user-visible behavior. Create or link a separate engineering handoff only when the user explicitly requests one.
13. Remove empty tables, artificial 不涉及 text, instructional prose, duplicated restatement, and detached implementation or testing plans. Before delivery, check that background explains a causal user problem, every list row names an independently reviewable user outcome, every detail row makes a distinct product decision, and every tracking event can answer a product or business question.