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 .agents/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**: STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat 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 
53STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat 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), STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat 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 .agents/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 STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. Ask whether they'd like a brief summary of PRODUCT.md appended to AGENTS.md for easier agent reference. If yes, append a short **Design Context** pointer section there.
157