pbakaus_impeccable/source/skills/impeccable/reference/teach.md

Teach Flow

Gathers design context for a project and writes two complementary files at the project root:

• PRODUCT.md (strategic): register, target users, product purpose, brand personality, anti-references, strategic design principles. Answers "who/what/why".
• DESIGN.md (visual): visual theme, color palette, typography, components, layout. Follows the Google Stitch DESIGN.md format. Answers "how it looks".

Every other impeccable command reads these files before doing any work.

Step 1: Load current state

Run the shared loader first so you know what already exists:

node {{scripts_path}}/load-context.mjs

The 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.

Decision tree:

• 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.
• PRODUCT.md exists, DESIGN.md missing: skip to Step 5 — offer to run /impeccable document for DESIGN.md.
• 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.
• Both exist: {{ask_instruction}} which to refresh. Skip the one the user doesn't want changed.
• Just DESIGN.md exists (unusual): do Steps 2-4 to produce PRODUCT.md.

Never silently overwrite an existing file. Always confirm first.

Step 2: Explore the codebase

Before asking questions, thoroughly scan the project to discover what you can:

• README and docs: Project purpose, target audience, any stated goals
• Package.json / config files: Tech stack, dependencies, existing design libraries
• Existing components: Current design patterns, spacing, typography in use
• Brand assets: Logos, favicons, color values already defined
• Design tokens / CSS variables: Existing color palettes, font stacks, spacing scales
• Any style guides or brand documentation

Also form a register hypothesis from what you find:

• Brand signals: /, /about, /pricing, /blog/*, /docs/*, hero sections, big typography, scroll-driven sections, landing-page-shaped content.
• Product signals: /app/*, /dashboard, /settings, /(auth), forms, data tables, side/top nav, app-shell components.

Register is a hypothesis at this point, not a decision — Step 3 confirms it.

Note what you've learned and what remains unclear. This exploration feeds both PRODUCT.md and DESIGN.md.

Step 3: Ask strategic questions (for PRODUCT.md)

{{ask_instruction}} Focus only on what you couldn't infer from the codebase.

Register (ask first — it shapes everything below)

Every 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).

If 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?"

If the signal is genuinely split (e.g. a product with a big marketing landing), {{ask_instruction}} which register describes the primary surface. The register can be overridden per task later, but PRODUCT.md carries one default.

Users & Purpose

• Who uses this? What's their context when using it?
• What job are they trying to get done?
• For brand: what emotions should the interface evoke? (confidence, delight, calm, urgency)
• For product: what workflow are they in? What's the primary task on any given screen?

Brand & Personality

• How would you describe the brand personality in 3 words?
• Reference sites or apps that capture the right feel? What specifically about them?
  • For brand, push for real-world references in the right lane (tech-minimal, editorial-magazine, consumer-warm, brutalist-grid, etc.) — not generic "modern" adjectives.
  • For product, push for category best-tool references (Linear, Figma, Notion, Raycast, Stripe).
• What should this explicitly NOT look like? Any anti-references?

Accessibility & Inclusion

• Specific accessibility requirements? (WCAG level, known user needs)
• Considerations for reduced motion, color blindness, or other accommodations?

Skip 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.

Step 4: Write PRODUCT.md

Synthesize into a strategic document:

# Product

## Register

product

## Users
[Who they are, their context, the job to be done]

## Product Purpose
[What this product does, why it exists, what success looks like]

## Brand Personality
[Voice, tone, 3-word personality, emotional goals]

## Anti-references
[What this should NOT look like. Specific bad-example sites or patterns to avoid.]

## Design Principles
[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".]

## Accessibility & Inclusion
[WCAG level, known user needs, considerations]

Register is either brand or product as a bare value. No prose, no commentary.

Write to PROJECT_ROOT/PRODUCT.md. If .impeccable.md existed, the loader already renamed it — merge into that content rather than starting from scratch.

Step 5: Decide on DESIGN.md

Offer /impeccable document either way. Two paths:

• 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?"
• 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?"

If the user agrees, delegate to /impeccable document (it auto-detects scan vs seed). Load its reference and follow that flow.

If the user prefers to skip, mention they can run /impeccable document any time later.

Step 6: Confirm and wrap up

Summarize:

• Register captured (brand / product)
• What was written (PRODUCT.md, DESIGN.md, or both)
• The 3-5 strategic principles from PRODUCT.md that will guide future work
• If DESIGN.md is pending, remind the user how to generate it later

Critical: re-run the loader to refresh session context. After writing PRODUCT.md, run node {{scripts_path}}/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.

If 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.

Optionally {{ask_instruction}} whether they'd like a brief summary of PRODUCT.md appended to {{config_file}} for easier agent reference. If yes, append a short Design Context pointer section there.