1# Teach Flow
  2
  3Gathers design context for a project and writes two complementary files at the project root:
  4
  5- **PRODUCT.md** (strategic): root project file for register, target users, product purpose, brand personality, anti-references, strategic design principles. Answers "who/what/why".
  6- **DESIGN.md** (visual): root project file for visual theme, color palette, typography, components, layout. Follows the [Google Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/format/). Answers "how it looks".
  7
  8Every other impeccable command reads these files before doing any work.
  9
 10## Step 1: Load current state
 11
 12Run the shared loader first so you know what already exists:
 13
 14```bash
 15node .trae-cn/skills/impeccable/scripts/load-context.mjs
 16```
 17
 18The output tells you whether PRODUCT.md and/or DESIGN.md already exist. If `migrated: true`, legacy `.impeccable.md` was auto-renamed to `PRODUCT.md`. Mention this once to the user.
 19
 20Decision tree:
 21- **Neither file exists (empty project or no context yet)**: do Steps 2-4 (write PRODUCT.md), then decide on DESIGN.md based on whether there's code to analyze.
 22- **PRODUCT.md exists, DESIGN.md missing**: skip to Step 5 and offer to run `/impeccable document` for DESIGN.md.
 23- **PRODUCT.md exists but has no `## Register` section (legacy)**: add it. Infer a hypothesis from the codebase (see Step 2), confirm with the user, write the field.
 24- **Both exist**: ask the user directly to clarify what you cannot infer. Ask which file to refresh. Skip the one the user doesn't want changed.
 25- **Just DESIGN.md exists (unusual)**: do Steps 2-4 to produce PRODUCT.md.
 26
 27Never silently overwrite an existing file. Always confirm first.
 28
 29If teach was invoked as a setup blocker by another command, such as `/impeccable craft landing page`, pause that command here. Complete teach, re-run the loader, then resume the original command with the freshly loaded context. For craft, resume into shape next; teach creates project context, but it is not a substitute for the task-specific shape interview and confirmed design brief.
 30
 31## Step 2: Explore the codebase
 32
 33Before asking questions, thoroughly scan the project to discover what you can:
 34
 35- **README and docs**: Project purpose, target audience, any stated goals
 36- **Package.json / config files**: Tech stack, dependencies, existing design libraries
 37- **Existing components**: Current design patterns, spacing, typography in use
 38- **Brand assets**: Logos, favicons, color values already defined
 39- **Design tokens / CSS variables**: Existing color palettes, font stacks, spacing scales
 40- **Any style guides or brand documentation**
 41
 42Also form a **register hypothesis** from what you find:
 43
 44- Brand signals: `/`, `/about`, `/pricing`, `/blog/*`, `/docs/*`, hero sections, big typography, scroll-driven sections, landing-page-shaped content.
 45- Product signals: `/app/*`, `/dashboard`, `/settings`, `/(auth)`, forms, data tables, side/top nav, app-shell components.
 46
 47Register is a hypothesis at this point, not a decision; Step 3 confirms it.
 48
 49Note what you've learned and what remains unclear. This exploration feeds both PRODUCT.md and DESIGN.md.
 50
 51## Step 3: Ask strategic questions (for PRODUCT.md)
 52
 53ask the user directly to clarify what you cannot infer. Ask only about what you couldn't infer from the codebase.
 54
 55### Interview mode, not confirmation mode
 56
 57If the repo is empty or the user's brief is sparse, run a short interview before proposing PRODUCT.md. Do **not** turn a one-sentence request into a complete inferred PRODUCT.md and ask for blanket confirmation.
 58
 59- Use the harness's structured question tool when one exists. Otherwise, ask directly in chat and stop.
 60- Ask **2-3 questions per round**, then wait for answers.
 61- Use inferred answers as hypotheses or options, not as finished facts.
 62- Complete at least one real user-answer round before drafting PRODUCT.md, unless every required answer is directly discoverable from repo docs.
 63- Round 1 should establish register, users/purpose, and desired outcome.
 64- Round 2 should establish brand personality or references, anti-references, and accessibility needs.
 65
 66### Minimum viable interview
 67
 68Ask enough to complete PRODUCT.md. At minimum, cover register confirmation, users and purpose, brand personality, anti-references, and accessibility needs unless each answer is directly discoverable from repo context. After at least one interview round, you may propose inferred answers, but the user must confirm them before you write PRODUCT.md. Never synthesize PRODUCT.md from the original task prompt alone.
 69
 70### Register (ask first; it shapes everything below)
 71
 72Every design task is either **brand** (marketing, landing, campaign, long-form content, portfolio: design IS the product) or **product** (app UI, admin, dashboards, tools: design SERVES the product).
 73
 74If Step 2 produced a clear hypothesis, lead with it: *"From the codebase, this looks like a [brand / product] surface. Does that match your intent, or should we treat it differently?"*
 75
 76If the signal is genuinely split (e.g. a product with a big marketing landing), ask the user directly to clarify what you cannot infer. Ask which register describes the **primary** surface. The register can be overridden per task later, but PRODUCT.md carries one default.
 77
 78### Users & Purpose
 79- Who uses this? What's their context when using it?
 80- What job are they trying to get done?
 81- For brand: what emotions should the interface evoke? (confidence, delight, calm, urgency)
 82- For product: what workflow are they in? What's the primary task on any given screen?
 83
 84### Brand & Personality
 85- How would you describe the brand personality in 3 words?
 86- Reference sites or apps that capture the right feel? What specifically about them?
 87  - For brand, push for real-world references in the right lane (tech-minimal, editorial-magazine, consumer-warm, brutalist-grid, etc.), not generic "modern" adjectives.
 88  - For product, push for category best-tool references (Linear, Figma, Notion, Raycast, Stripe).
 89- What should this explicitly NOT look like? Any anti-references?
 90
 91### Accessibility & Inclusion
 92- Specific accessibility requirements? (WCAG level, known user needs)
 93- Considerations for reduced motion, color blindness, or other accommodations?
 94
 95Skip questions where the answer is already clear. **Do NOT ask about colors, fonts, radii, or visual styling here.** Those belong in DESIGN.md, not PRODUCT.md.
 96
 97## Step 4: Write PRODUCT.md
 98
 99Write PRODUCT.md only after the user has confirmed the strategic answers from Step 3. If an inferred answer is uncertain or unconfirmed, ask before writing.
100
101Synthesize into a strategic document:
102
103```markdown
104# Product
105
106## Register
107
108product
109
110## Users
111[Who they are, their context, the job to be done]
112
113## Product Purpose
114[What this product does, why it exists, what success looks like]
115
116## Brand Personality
117[Voice, tone, 3-word personality, emotional goals]
118
119## Anti-references
120[What this should NOT look like. Specific bad-example sites or patterns to avoid.]
121
122## Design Principles
123[3-5 strategic principles derived from the conversation. Principles like "practice what you preach", "show, don't tell", "expert confidence". NOT visual rules like "use OKLCH" or "magenta accent".]
124
125## Accessibility & Inclusion
126[WCAG level, known user needs, considerations]
127```
128
129Register is either `brand` or `product` as a bare value. No prose, no commentary.
130
131Write to `PROJECT_ROOT/PRODUCT.md`. If `.impeccable.md` existed, the loader already renamed it; merge into that content rather than starting from scratch.
132
133## Step 5: Decide on DESIGN.md
134
135Offer `/impeccable document` either way. Two paths:
136
137- **Code exists** (CSS tokens, components, a running site): "I can generate a DESIGN.md that captures your visual system (colors, typography, components) so variants stay on-brand. Want to do that now?"
138- **Pre-implementation** (empty project): "I can seed a starter DESIGN.md from five quick questions about color strategy, type direction, motion energy, and references. You can re-run once there's code, to capture the real tokens. Want to do that now?"
139
140If the user agrees, delegate to `/impeccable document` (it auto-detects scan vs seed). Load its reference and follow that flow.
141
142If the user prefers to skip, mention they can run `/impeccable document` any time later.
143
144## Step 6: Confirm and wrap up
145
146Summarize:
147- Register captured (brand / product)
148- What was written (PRODUCT.md, DESIGN.md, or both)
149- The 3-5 strategic principles from PRODUCT.md that will guide future work
150- If DESIGN.md is pending, remind the user how to generate it later
151
152**Critical: re-run the loader to refresh session context.** After writing PRODUCT.md, run `node .trae-cn/skills/impeccable/scripts/load-context.mjs` one final time and let its full JSON output land in conversation. This ensures subsequent commands in this session use the freshly-written PRODUCT.md, not a stale earlier version.
153
154If teach was invoked as a blocker by another impeccable command (e.g. the user ran `/impeccable polish` with no PRODUCT.md), resume that original task now with the fresh context.
155
156Optionally ask the user directly to clarify what you cannot infer. Ask whether they'd like a brief summary of PRODUCT.md appended to RULES.md for easier agent reference. If yes, append a short **Design Context** pointer section there.