pbakaus_impeccable/.github/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 the user directly to clarify what you cannot infer. 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 the user directly to clarify what you cannot infer. 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 the user directly to clarify what you cannot infer. 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 the user directly to clarify what you cannot infer. whether they'd like a brief summary of PRODUCT.md appended to .github/copilot-instructions.md for easier agent reference. If yes, append a short Design Context pointer section there.