flow-design

Flow Design

Transform frozen requirements into structured flow diagrams and interaction sequences.

Hard Gate

Prerequisite: project-governor:requirements-freeze must be complete.

• Verify: docs/governor/specs/ contains a dated requirements spec.
• Verify: docs/governor/project.yaml has requirements in phases_completed.

If not met, refuse and tell user to run project-governor:requirements-freeze first.

PDCA Cycle

digraph flow_pdca {
    rankdir=LR;
    node [shape=box, style=filled];
    "P: Define flow scope" [fillcolor="#E3F2FD"];
    "D: Design + document flows" [fillcolor="#E8F5E9"];
    "C: Gate-check flows" [fillcolor="#FFF3E0"];
    "A: Accept or rework" [fillcolor="#F3E5F5"];

    "P: Define flow scope" -> "D: Design + document flows" -> "C: Gate-check flows" -> "A: Accept or rework";
    "C: Gate-check flows" -> "D: Design + document flows" [label="fail", style=dashed];
}

Plan

• 目标：从需求规格中提炼出完整的流程、数据流、错误流
• 输入：frozen requirements spec (docs/governor/specs/)
• 验收标准：每个需求至少对应一个流程步骤，流程间无矛盾

Do

1. Load requirements — Read the latest spec from docs/governor/specs/ 语言要求：本次委托产出的所有文档必须使用中文撰写。如果被委托的 skill 输出英文内容，在保存为 artifact 之前必须翻译为中文。专业术语可在括号内保留英文原文。
2. Delegate to superpowers:brainstorming — Use brainstorming to collaboratively design the flows, 严格遵循渐进式提问原则：
   • 逐个提问，不要批量抛出：每次只问 1 个问题（最多 2 个强相关问题），等用户回答后再决定下一个问题
   • 前答决定后问：每个问题的答案会影响后续问题的方向。例如：
     • "系统有哪些主要流程？" → 答案决定接下来追问哪个流程的细节
     • "数据在流程间如何流转？" → 答案决定需要问哪些数据格式/转换问题
     • "哪里可能出错？" → 答案决定需要设计哪些恢复路径
   • 先搞清主干流程，再追问分支：按 "主流程 → 数据流 → 错误流" 的层次递进，主干未定时不要问边界情况
   • 跳过不相关的问题：如果前面的答案已经隐含了某些信息，直接跳过对应的问题，不要机械地问一遍
3. Produce flow artifacts — Write to docs/governor/flows/YYYY-MM-DD-<project-name>-flows.md. Include:
   • Process Flow — graphviz dot diagrams showing main processes and their sequences
   • Data Flow — what data moves between processes, in what format
   • Error Flow — failure modes and recovery paths
   • Type-specific:
     • Type A: command dispatch flow, agent pipeline flow, I/O boundary flow
     • Type B: user journey flow, page navigation flow, API interaction flow

Check (阶段门禁)

Dispatch gate-checker agent against shared/gate-templates/flow-gate.md:

• All required flow types present (process, data, error)
• Every requirement covered by at least one flow step
• Flow steps reference specific requirement numbers
• No orphan flows (every step maps to a requirement)
• Type-specific flows present
• No placeholder content, graphviz valid

Gate verdict → PASS / CONDITIONAL / FAIL

Act

• PASS: Append flow to phases_completed, set current_phase: flow. Write gate record. 更新 docs/governor/INDEX.md：更新当前阶段，追加产物记录行。
  • If auto: true in project.yaml: Automatically invoke project-governor:state-design.
  • If auto: false: Prompt: "Flow design complete. Next: invoke project-governor:state-design"
• CONDITIONAL: Fix minor gaps inline, re-Check.
• FAIL: Return to Do — address gaps, re-Check.

Flow Notation

Use inline graphviz dot blocks in markdown for all flow diagrams. Example:

digraph example {
    input -> validate -> transform -> output;
    validate -> error_handler [label="invalid"];
    error_handler -> input [label="retry"];
}

PDCA Context

Each phase is a self-contained PDCA loop. This phase receives frozen requirements as input and produces verified flows that feed into state design.