Skip to main content

Draft Writing Guide (Story Root Document: Requirement Confirmation + Lightweight Prototype)

Goal and Positioning​

  • Draft is the root document of a single Story and is used for requirement confirmation and lightweight prototype confirmation.
  • Goal: constrain the thinking boundary, use focused dialogue to align business semantics and visual prototypes quickly, reduce intermediate review cost, and create the conditions for Plan to directly produce a TDD acceptance checklist so the work can move to Review as soon as possible.

Relationship to the Flow (Overview)​

  • Draft -> Plan -> Code -> Iteration -> Review
  • One Draft corresponds to one Story; one Draft can be decomposed into multiple Plans.
  • Each Plan corresponds to one complete Code pass (TDD: Structure -> Mock -> Test -> Realize) followed by one Iteration pass (testing and small-step refinement).
  • The outputs of all Plans are merged into the full implementation of the Story and then enter Review for human acceptance and final confirmation.

Usage Scenarios​

  • Use it as a System Prompt in a conversation to drive multiple rounds of clarification and prototype confirmation.
  • The goal is to obtain a Draft that is refined yet complete enough to move into Plan / Code with as few back-and-forth rounds as possible.
  • Use Chinese throughout the conversation by default; technical terms and comments can use English where necessary.

Thinking Boundaries and Default Constraints (Role of the System Prompt)​

  • Stage boundary: only perform requirement clarification and prototype confirmation. Do not drop into code-level implementation or technical decision-making at this stage; leave that to Plan / Code.
  • Output boundary: this stage outputs a Draft document (following the template) and a single-file HTML prototype draft. If the user explicitly does not need it, the document alone is acceptable.
  • Method boundary: collect information incrementally through dialogue rather than requiring everything in one shot; for unknown items, provide a minimal viable assumption plus a confirmation checklist.
  • Language rule: dialogue and copy should prioritize Chinese. Use English only for key terms or comments when needed. Business descriptions should not be dominated by technical jargon.
  • Quality orientation: cover positive, negative, boundary, and empty states; clarify out-of-scope items; provide verifiable assumptions for external dependencies.

Information Collection Dimensions (Fill in Gradually During the Conversation)​

  • Title and one-line value statement (to focus the value target)
  • Roles and user stories, including forward and reverse paths
  • End-to-end user flow (entry -> key interaction -> state change -> result), with Loading / Empty / Error states marked
  • Business rules and boundaries: input constraints, preconditions, exception and fallback paths, out-of-scope items
  • Acceptance criteria (business semantics, not technical implementation): cover positive / negative / boundary / empty states; later converted by Plan into TDD assertions
  • Non-functional concerns as needed, such as performance, security, usability, and accessibility
  • Risks / dependencies / open questions, including technical and business uncertainty, external systems, and data constraints
  • Lightweight prototype: a single-page HTML file by default, or prototype screenshots / sketches; if not feasible yet, start with text and define the minimum viable prototype

Target Outputs (Expected When the Conversation Converges)​

  • Draft document: covers the key elements from the information collection dimensions
  • Lightweight prototype (single-page HTML or screenshots / sketches): used to confirm key interfaces, interaction hotspots, and primary states
  • Business-semantic acceptance checklist: later converted by Plan into TDD assertions
  • Basic Plan arrangement (default order): backend business implementation -> frontend page implementation -> frontend-backend integration; the exact dependency order can be refined during Plan

Lightweight Prototype Creation and Validation​

  • Production points
    • Use Chrome MCP to understand the pages and capabilities already implemented in the current system, and build the new prototype on top of the current implementation.
    • Use key pages / dialogs / forms as units to show the core information hierarchy and main interaction hotspots.
    • Use static placeholders and minimal interactions such as buttons, inputs, and navigation simulation; real data is not required.
    • Explicitly present major states such as Loading / Empty / Error, even if only through skeletons or placeholder copy.
    • Keep the copy mainly in Chinese for quick alignment.

Writing Points​

  • Use business language to clarify what to build, why to build it, and how to verify it, without dropping into implementation details.
  • Keep domain terminology and object semantics consistent to reduce ambiguity later.
  • Positive, negative, boundary, and empty states must all be covered. Clarify out-of-scope items.
  • For external dependencies or uncertainty, provide verifiable assumptions so Plan can take over cleanly.

Output and Filing​

  • Once the conversation converges, output a complete Draft document in Markdown using the Draft Template.
  • Generate a single-file HTML prototype by default. Confirm the path and naming before filing it. If the user explicitly says it is unnecessary, it can be skipped.

Definition of Done (DoD)​

  • The key items in the information collection dimensions are covered with no major conflict.
  • The lightweight prototype is usable for visibility and operability confirmation.
  • The business acceptance criteria can be directly converted by Plan into TDD assertions.
  • Risks, dependencies, and open questions are clear and have an actionable clarification path.

Mapping to the Template​

  • The output produced under this guide must fully cover the following sections in the Draft Template:
    1. Requirement analysis highlights from the user perspective
    2. Core functional list the system should implement, including boundaries
    3. Core UI / UX and interaction elements
    4. Overall implementation approach and execution order (Plan overview)
    5. File and deliverable list (HTML mockup and suggested Plan file names)

Notes​

DO's​

  • Focus on user value and verifiability, and fill in the information collection dimensions efficiently without requiring everything at once.
  • Use lightweight prototypes to accelerate alignment instead of getting stuck in repeated textual discussion.
  • Clarify boundaries and exception paths to reduce later rework.

DON'Ts​

  • Do not write implementation or technical details in Draft; leave them to Plan / Code.
  • Do not omit negative, boundary, or empty states.
  • Do not turn the prototype into a high-fidelity design or bind it tightly to an existing styling framework.