1  # Workflow: Supporting Guide for Question-First Delivery
  2  
  3  This file supports `SKILL.md`. It does not define an independent product workflow.
  4  
  5  The runtime contract lives in `SKILL.md`:
  6  - new ambiguous tasks start with structured step-by-step confirmation
  7  - richly specified briefs can skip most clarification, but still require a visible plan
  8  - follow-up iterations and minor fixes act directly unless scope changes
  9  
 10  Use this file to structure the step-by-step confirmation flow and the follow-through after that decision has already been made.
 11  
 12  ---
 13  
 14  ## Relationship to 8-Layer Design Framework
 15  
 16  This workflow is the **execution process**. The 8-layer framework (`design-thinking-framework.md`) is the **thinking structure**.
 17  
 18  **Mapping:**
 19  
 20  | Workflow Step | 8-Layer Framework | Purpose |
 21  |---------------|-------------------|---------|
 22  | **Step 1: Understand** (Structured confirmation) | Layer 1 (Goal) + Layer 2 (Information) | Clarify objectives, audience, scope, information priorities |
 23  | **Step 2: Route** (Load references) | Layer 2-7 (task-dependent) | Load theory and patterns for relevant layers |
 24  | **Step 3: Acquire Context** (Design system/brand) | Layer 6 (Brand) + Layer 7 (System) | Understand existing constraints and brand personality |
 25  | **Step 4: Plan** (Visible execution plan) | Layer 1-7 (condensed) | Turn confirmed facts and assumptions into a build plan |
 26  | **Step 5: Approval** (Manager review) | Layer 8 (Validation) | Confirm direction before expensive execution |
 27  | **Step 6: Design** (Build artifacts) | Layer 3 (Structure) + Layer 4 (Interaction) + Layer 5 (Visual) | Execute structure, interaction, and visual design |
 28  | **Step 7: Verify** (Check quality) | Layer 8 (Validation) | Test technical feasibility, usability, design quality |
 29  | **Step 8: Iterate** (Refine based on feedback) | Layer 8 → Layer 1 (feedback loop) | Use validation results to refine goals and execution |
 30  
 31  **When to use which:**
 32  - **Use workflow.md** for step-by-step execution guidance
 33  - **Use design-thinking-framework.md** when you need to diagnose problems, resolve conflicts, or understand "why" behind decisions
 34  - **Use both together** for complex multi-screen flows or design system creation
 35  
 36  ## Runtime Load Announcements
 37  
 38  Treat runtime loading as visible work, not invisible thought. `load-manifest.json` is the source of truth for route bundles, checkpoint bundles, and optional inspiration bundles. Bundle matching is done by an Agent subagent that reads the catalog from `scripts/generate-bundle-catalog.mjs` and semantically matches the user's prompt. `scripts/resolve-load-bundles.mjs` is kept as a keyword-based fallback.
 39  
 40  Rules:
 41  - announce before reading runtime references or copying templates
 42  - use the exact line format: `Load: because=<reason> loaded=<comma-separated paths>`
 43  - if the bundle is already loaded, say `Load: because=<reason> already_loaded=<comma-separated paths>`
 44  - use stable reasons from `load-manifest.json` such as `all-design-tasks`, `question-first-delivery`, `deep-design-review`, `react-prototype`, `before-animation`, `before-delivery`
 45  - do not announce ordinary codebase reads that are not part of the skill runtime bundle
 46  - do not silently skip bundle loads; explicit dedupe is part of the contract
 47  
 48  Bundle classes:
 49  - **Base-required bundles (`基础必载`)** — always load for every design task
 50  - **Conditionally required bundles (`条件命中后必载`)** — load when a `taskType` or `checkpoint` is triggered
 51  - **Truly optional inspirations (`真正可选`)** — load only when case-study inspiration helps
 52  
 53  ## Two-Stage Routing
 54  
 55  Use a two-stage route instead of loading every plausible reference up front.
 56  
 57  **Stage 1: Base-required load**
 58  - always load `all-design-tasks`
 59  - if the task is new or underspecified, also load `question-first-delivery`
 60  
 61  **Stage 2: Route-shaping questions**
 62  - ask the fixed question batch below
 63  - map those answers directly to `taskTypes` and `checkpoints`
 64  - only after explicit mapping, use semantic matching to supplement unresolved `taskTypes` or `optionalInspirations`
 65  
 66  This keeps typography, layout, and visual/color theory in the default context while preserving conditional loading for brand, interaction, export, animation, device mockups, and review work.
 67  
 68  ## First-Turn Rule
 69  
 70  Treat this as supporting guidance, not an override:
 71  
 72  - **Use structured confirmation** for new tasks with missing audience, scope, output shape, hard constraints, or reference context
 73  - **Skip most questions** only when the brief is already rich, or the user explicitly asks to move fast
 74  - **Act directly** for follow-up iterations and minor fixes
 75  
 76  If you are unsure which path applies, default to the next blocking confirmation step. Do not invent a fourth path.
 77  
 78  ## The Art of Asking Questions
 79  
 80  Ask **in steps**, not as a long unstructured dump.
 81  
 82  Default target:
 83  - 3 to 4 confirmation steps
 84  
 85  Preferred shape:
 86  - 1 blocking question per step
 87  - 2 to 4 short options
 88  - optional freeform when the platform supports it
 89  
 90  Fallback:
 91  - if the platform has no structured question UI, compress these steps into one compact batch message
 92  
 93  After the steps:
 94  - stop once blocking fields are resolved
 95  - ask at most one open follow-up round if critical details remain
 96  - if critical fields are still unknown after that, convert them into explicit assumptions in the visible plan
 97  
 98  Critical blocking fields:
 99  - output shape
100  - audience
101  - scope
102  - hard constraints that would materially change the direction
103  - reference source, or an explicit "no reference"
104  - success criteria
105  - existing contract update mode (`DESIGN.md`: append / merge / overwrite) when relevant
106  
107  Non-blocking fields:
108  - optional refinements
109  - tweak controls
110  - secondary taste preferences
111  
112  ## Required Question Checklist
113  
114  When you are in the question-first path, ask these **route-shaping questions first** and stop once bundle selection is clear:
115  
116  ### 1. Output Type
117  
118  - What is the first artifact: page, deck, clickable prototype, animation, design system, critique, or export target?
119  - Route mapping:
120    `page → landing-page`
121    `deck → slide-deck`
122    `clickable prototype → interactive-prototype`
123    `animation → animation-motion`
124    `design system → design-system-creation`
125    `critique/review/audit → deep-design-review`
126    `pdf/pptx/video target → pdf-export` / `editable-pptx-export` / `video-export`
127  
128  ### 2. Task State
129  
130  - Is this a new task, a localized edit, or an approved follow-up iteration?
131  - Route mapping:
132    `new or underspecified → question-first-delivery`
133    `localized edit / approved follow-up → skip question-first unless scope changed`
134  
135  ### 3. Available Context
136  
137  - Is there an existing design system, UI kit, codebase, screenshots, or a brand reference?
138  - Is there an existing `DESIGN.md` or equivalent contract file?
139  - Route mapping:
140    `brand reference / clone → brand-style-clone`
141    `need real assets/logo sourcing → brand-asset-acquisition`
142    `no references → no-design-system`
143  
144  **If there is already a `DESIGN.md`:**
145  - Ask how to update it before touching it
146  - Required mode selection: **Append / Merge / Overwrite**
147  - Recommend **Merge** by default
148  - Do not silently rewrite the file just because a new direction sounds better
149  
150  ### 4. Interaction, Device, and Export Constraints
151  
152  - Does the task need interaction, an iOS/Android frame, or export output?
153  - Route mapping:
154    `interactive flow → interactive-prototype` or `interaction-design`
155    `iOS → mobile-mockup + before-ios-mockup`
156    `PDF / PPTX / video → matching export task type + before-export`
157  
158  ### 5. Primary Design Risk
159  
160  - What is most likely to go wrong: layout, typography, color, information hierarchy, interaction, or brand tone?
161  - Route mapping:
162    `layout → layout-problems`
163    `typography → typography-problems`
164    `color → color-problems`
165    `information hierarchy → information-architecture`
166    `interaction → interaction-problems`
167    `brand tone → brand-tone`
168  
169  ## After Routing Is Locked
170  
171  After bundle selection is clear, ask only the remaining blocking product questions. For example:
172  
173  **Building a landing page**:
174  - What is the target conversion action?
175  - Primary audience?
176  - Competitor references?
177  - Who provides the copy?
178  
179  **Building an iOS App onboarding**:
180  - How many steps?
181  - What does the user need to do?
182  - Skip paths?
183  - Target retention rate?
184  
185  **Building an animation**:
186  - Duration?
187  - Final use (video asset/website/social)?
188  - Rhythm (fast/slow/segmented)?
189  - Key frames that must appear?
190  
191  ## Structured Confirmation Example
192  
193  When encountering a new task, prefer this structure:
194  
195  ```markdown
196  Step 1 — Output
197  What is the first artifact?
198  - Landing page / marketing page
199  - Deck / presentation
200  - Clickable prototype
201  - Animation / motion study
202  
203  Step 2 — Task state
204  What kind of task is this?
205  - New task
206  - Localized edit
207  - Approved follow-up
208  
209  Step 3 — Context
210  What should I route around?
211  - Existing design system / codebase
212  - Brand reference or clone
213  - Need asset sourcing
214  - No references
215  
216  Step 4 — Constraints
217  Any special delivery or device constraints?
218  - Interactive flow
219  - iOS mockup
220  - Export PDF / PPTX / video
221  - No special constraints
222  
223  Step 5 — Primary risk
224  Where should I deepen theory?
225  - Layout / information hierarchy
226  - Typography
227  - Color / tone
228  - Interaction
229  
230  Step 6 — Plan
231  Plan
232  - Goal: ...
233  - Confirmed facts: ...
234  - Assumptions: ...
235  - First artifact: ...
236  - Variation axes: ...
237  - Verification: ...
238  
239  Approve this plan, or tell me what to change before I build.
240  ```
241  
242  If the platform lacks structured question UI, convert the same flow into one compact text block.
243  
244  ## After the Confirmation Steps
245  
246  Once the confirmation steps are answered, or once unanswered critical fields have been converted into explicit assumptions, do not move straight into delivery. Produce a visible plan, wait for approval, then build.
247  
248  ### Planning Gate
249  
250  A task is ready for planning when:
251  - audience is known or explicitly assumed
252  - output shape is known
253  - scope is known
254  - hard constraints are known
255  - reference context is known or explicitly absent
256  - success criteria are known or explicitly assumed
257  
258  If these are incomplete, keep clarifying. If the user wants speed, compress the questions, but do not skip the plan.
259  
260  ### Execution Plan
261  
262  Before building, show a short plan:
263  
264  ```html
265  <!--
266  Execution plan:
267  - Goal: ...
268  - Confirmed facts: ...
269  - Assumptions: ...
270  - First artifact: ...
271  - Variation axes: ...
272  - Verification: ...
273  
274  Approve this plan before I continue into the full build.
275  -->
276  ```
277  
278  Rules:
279  - 4 to 6 bullets maximum
280  - this is visible to the user
281  - approval is required before the first full build
282  - rich briefs may skip questioning, but not planning
283  - do not reopen the full question flow unless audience, scope, or output type changes
284  
285  ### Main Work
286  
287  After the plan is approved:
288  - Write React components to replace placeholders
289  - Create variations (using design_canvas or Tweaks)
290  - If it's slides/animation, start with starter components
291  - announce any newly loaded runtime bundle before reading it, even mid-task when a checkpoint triggers
292  - if you chose the question-first path, route with `question-first-delivery` plus the bundles locked by the route-shaping answers
293  - if the user asked for critique/review/audit/score, route with `deep-design-review` before judging the work
294  
295  Show again halfway through. If the design direction is wrong, showing late means wasted work.
296  
297  ### Detail Polish
298  
299  After the user is satisfied with the overall direction, polish:
300  - Font size/spacing/contrast fine-tuning
301  - Animation timing
302  - Edge cases
303  - Tweaks panel refinement
304  
305  ### Verification + Delivery
306  
307  - Use Playwright to screenshot (see `references/verification.md`)
308  - Open in browser and visually confirm after the **final** edit
309  - Review the full page **and** every changed section; do not stop at the first viewport
310  - For responsive work, check at least desktop + one narrow/mobile viewport
311  - For iterative edits on an existing long page, treat touched sections as mandatory coverage targets
312  - Never declare "done" from code inspection alone
313  - Summarize **minimally**: only mention caveats and next steps
314  
315  ## The Deep Logic of Variations
316  
317  Giving variations is not creating choice paralysis for the user, it is **exploring the possibility space**. Let the user mix and match to arrive at the final version.
318  
319  ### What good variations look like
320  
321  - **Clear dimensions**: each variation varies on a different dimension (A vs B only changes color, C vs D only changes layout)
322  - **Gradient**: from "by-the-book conservative version" to "bold novel version" in progressive steps
323  - **Labels**: each variation has a short label explaining what it's exploring
324  
325  ### Implementation Methods
326  
327  **Pure visual comparison** (static):
328  → Use `assets/design_canvas.jsx`, grid layout side by side. Each cell has a label.
329  
330  **Multi-option/interaction differences**:
331  → Build complete prototypes, switch with Tweaks. For example, building a login page, "layout" is one tweak option:
332  - Left copy, right form
333  - Top logo + centered form
334  - Full-bleed background image + floating form overlay
335  
336  The user toggles Tweaks to switch, no need to open multiple HTML files.
337  
338  ### Exploration Matrix Thinking
339  
340  For every design, mentally go through these dimensions and pick 2-3 to give variations on:
341  
342  - Visual: minimal / editorial / brutalist / organic / futuristic / retro
343  - Color: monochrome / dual-tone / vibrant / pastel / high-contrast
344  - Typography: sans-only / sans+serif contrast / all serif / monospace
345  - Layout: symmetric / asymmetric / irregular grid / full-bleed / narrow column
346  - Density: sparse breathing / moderate / information-dense
347  - Interaction: minimal hover / rich micro-interactions / exaggerated large animations
348  - Texture: flat / layered shadows / textured / noise / gradient
349  
350  ## When Facing Uncertainty
351  
352  - **Don't know how to proceed**: Honestly say you're unsure, ask the user, or put a placeholder and continue. **Don't fabricate.**
353  - **User's description is contradictory**: Point out the contradiction, let the user choose one direction.
354  - **Task is too large to handle at once**: Break into steps, do the first step for the user to review, then proceed.
355  - **Effect the user wants is technically difficult**: Explain the technical boundary clearly, provide alternatives.
356  
357  ## Summary Rules
358  
359  When delivering, the summary should be **extremely brief**:
360  
361  ```markdown
362  ✅ Slides completed (10 slides), with Tweaks to switch "night/day mode".
363  
364  Note:
365  - Data on slide 4 is fake, waiting for you to provide real data for replacement
366  - Animation uses CSS transition, no JS needed
367  
368  Next step suggestion: open in your browser first, tell me if any issues on which page/which part.
369  ```
370  
371  Don't:
372  - List the contents of every page
373  - Repeatedly explain what technology you used
374  - Brag about how good your design is
375  
376  Caveats + next steps, done.