define-workflow-refine

Refine — Idea Convergence

Domain: workflow | Constitution: Articles 1 (Surface Assumptions), 8 (Manage Confusion)

Entry/Exit

• Entry: vague idea, feature request, user's "I want to build X"
• Exit: docs/features/YYYYMMDD-<name>/01-spec.md + user approval
• Points to: upon completion must call define-workflow-spec
• Output path: → define-workflow-spec
• Preload: CANON.md
• Auxiliary references: refine-artifacts.md(Goal Review scoring table, External Scan template, Scout Output template, Spec One-Pager template, good/bad examples)

When not to use

• Requirements are already clearly structured, write the spec directly
• Trivial changes such as typos/single-line fixes

Hard gates

Agent Dispatch Contract

/refine The main execution persona is agents/requirements-analyst.md。

• External Scan may be executed by an independent subagent, but must be bound by this skill's Fact / Pattern / Inference / Unknown / Adopt / Reject output contract
• Idea Scout Army selects according to Phase 1.6 minimum trigger conditions agents/refine-ceo-scout.md、agents/refine-eng-scout.md、agents/refine-design-scout.md、agents/refine-content-scout.md
  • artifact_type: software → default CEO + Eng; involves UI / compliance → add Design
  • artifact_type: document / article → default CEO + Content
  • artifact_type: deck → default CEO + Content; add Design when there is an obvious visual/layout direction
  • artifact_type: visual → default CEO + Design
  • Small changes → may skip
• Unselected scouts do not produce placeholder feedback; feedback from all selected scouts is merged by the main session with tiering

Core anchors

5W1H Structured Clarification

Ask clarifying questions one at a time, one per message, do not list them out. Prefer structured questioning tools (such as AskUserQuestion); when unavailable, degrade to short plain text.

Execution rules:

• 6 mandatory question dimensions: problem/background, target users, success criteria, artifact type (runtime artifact_type, default software), constraints, context
• When the requirement is refactoring project-level workflow contracts, role matrices, or pipeline semantics, additionally mark the canonical first-level delivery category:software / content / visual
• Before asking questions, first Glob/Grep/Read to scan project context — cite specific files, do not ask questions from a state of ignorance

External Scan Protocol

Before proposing a solution, first determine whether it is necessary to search the external world. Use the WebSearch/browser/document retrieval available in the current host. When tools are unavailable, record "Search unavailable".

Execution rules:

• Execute by default: medium-to-large features,artifact_type non-software, introducing new dependencies, user asks "is there an existing solution"
• Skip: single-file fixes, user explicitly prohibits internet access, existing materials provide sufficient basis
• Output must be layered as Fact / Pattern / Inference / Unknown / Adopt / Reject (template see refine-artifacts.md）
• Search results cannot directly become requirements; only content that enters Adopt and is consistent with the goal/constraints can enter the solution
• Scan results older than 30 days are marked [可能过时]; for search targets by artifact type see refine-artifacts.md
• If executed by a subagent, it must be read-only, return no more than 1200 characters; returning raw search results, long quotes, complete webpage excerpts, or irrelevant background is prohibited
• The External Scan subagent only delivers Fact / Pattern / Inference / Unknown / Adopt / Reject summaries and source links; the main session is responsible for turning Adopt items into requirement judgments

Scout Army Dispatch

After Phase 1 is complete and before proposing solutions, dispatch scouts in parallel to verify feasibility.

Execution rules:

• Input: user clarification + artifact_type + (if applicable) canonical primary delivery category + External Scan summary + project context + do-not-do/to-be-confirmed boundaries
• Unified output structure (template see refine-artifacts.md）：Verdict + Evidence + Findings + Spec Impact
• Three levels of feedback: Blocking (must be resolved), Important (if not adopted, reason must be recorded), Suggestion (judge independently)

Pressure Test Proposals

Propose 2-3 solutions, each with pros and costs.

Execution rules:

• Each solution is tested on three dimensions: user value (painkiller or vitamin), feasibility (what is the hardest part), differentiation (essentially different from existing solutions)
• Hidden assumptions must be made explicit: what you are betting is true, what would kill the solution, what you choose to ignore and why

Process

Phase 1: Understanding and Exploration (Divergence)

Step 1.1 Explore project context (5W1H anchor execution rule 2)

Step 1.2 Scope check — when there are multiple independent subsystems, first decompose into subprojects, and only refine the first one

Step 1.2.5 Goal Review — scoring dimensions and template see refine-artifacts.md. 10-12 = accepted; 7-9 = needs-refinement; 0-6 = blocked. Small changes may skip but must have completion criteria

Step 1.3 5W1H clarification (anchor execution)

Step 1.4 Phase 1.4: External Scan (anchor execution)

Step 1.5(Optional) When UI mockup/flowchart is involved, ask in a separate message whether to display it with browser

Step 1.6 Scout Army (anchor execution)

Phase 2: Solutions and Convergence

Based on all Phase 1 inputs, propose 2-3 solutions and Pressure Test them (anchor execution).

Phase 3: Produce spec

Output a structured one-pager to docs/features/YYYYMMDD-<name>/01-spec.md. Full template see refine-artifacts.md。The "do-not-do list" is one of the most valuable parts of the spec.

Validation failure handling

Failure scenario	Handling method
User rejects the direction	Ask clearly for the reason, correct assumptions, return to Phase 1
Failed to converge on a solution	Expand the search scope or narrow the target scope
Hidden assumption is overturned	Update the assumption set, assess impact, possibly adjust direction
Discover an existing similar solution	Analyze the differences, and continue only after confirming a new solution is needed
Scope explodes	Decompose into subprojects, and only refine the first one

Common sayings

Saying	Reality	Consequence
"This is simple and doesn't need design"	Simple projects are exactly where unchecked assumptions cause the most rework.	"Simple" projects that skip clarification get reworked 3-5x
"Let's just do one direction and see"	A single solution cannot compare trade-offs.	When a wrong direction is discovered, the fix cost is 10-50x
"We'll add these features later"	Defining the scope of the MVP is about focus. The do-not-do list is more important than the do list.	Requirement creep → release delayed 2-4 weeks
"Stop asking, just do it"	Skipped clarification questions will definitely come back. 15 minutes of clarification > 15 hours of rework.	Assumptions exposed during the implementation phase add 4-8 hours per overturn

Red Flags

• Skipping "who is it for" and jumping straight into design
• Jumping to implementation without converging on 2-3 options
• Not asking "has anyone tried this before"
• Continuing into plan/build when Goal Review Score is below 10
• Done When is unverifiable or missing Stop Conditions
• Not making hidden assumptions explicit
• Not decomposing first when multiple independent subsystems are involved
• yes-machine mode: not questioning weak options
• Writing any code or invoking implementation skills before user approval

Verification Checklist

• "Who is it for and what problem does it solve" is defined
• Goal Review is completed or explicitly skipped (with valid justification)
• artifact_type is specified
• If discussing a long-term workflow contract: the canonical top-level delivery category is specified
• External Scan is completed/skipped/marked unavailable, and the reason is recorded
• Search results distinguish Fact / Pattern / Inference / Unknown / Adopt / Reject
• Necessary scouts have been dispatched and feedback has been merged
• Multiple directions were explored, not just the first idea
• Hidden assumptions are listed (including verification plans)
• The "not doing list" makes trade-offs explicit
• The output is a spec file
• The user approved the direction

Output Template

# [功能名称] — Spec

artifact_type: [software/document/article/deck/visual]
delivery_class: [software/content/visual]  # 仅在需要表达长期项目真相时使用
Goal Review Score: [score]/12 | Status: [accepted/needs-refinement/blocked]
One-line Goal: [一句话]
Done When: [Functional + Technical + Regression + Output]
Stop Conditions: [停止条件]
External References: [Fact/Pattern/Inference/Unknown/Adopt/Reject]
核心假设: [假设 — 验证方式]
MVP 范围: Include [最小可验证] / Exclude [明确排除]
不做清单: [事项 — 理由]

For the full template and good/bad examples, see refine-artifacts.md。