[BLOCKING] Execute skill steps in declared order. NEVER skip, reorder, merge steps without explicit user approval. [BLOCKING] Before each step or sub-skill call, update task tracking:
in_progresson start,completedon end. [BLOCKING] Every completed/skipped step MUST include evidence or explicit skip reason. [BLOCKING] If Task tools unavailable, maintain equivalent step-by-step plan tracker with same status transitions.
Quick Summary
Goal: Ship a correct, fully-verified feature that satisfies the saved Goal Contract — implemented with deep research, comprehensive planning, and maximum quality verification (planned, reviewed, tested, documented) — with no skipped quality gate on any non-trivial change.
Summary: Resolve the saved goal and spec contract, research and trace the feature, obtain an approved plan, implement in verified phases, run tests and reviews, reconcile specs and docs, and close with evidence; use fast mode only when every trivial-task condition is satisfied.
Workflow:
- Research — Deep investigation, multiple researcher subagents
- Plan — Detailed plan via
/plan; user approval required - Implement — Execute with full code review + SRE review
- Verify — Run all tests, review changes, update docs
Key Rules:
- Maximum thoroughness: research → plan → implement → review → test → docs
- User approval required at plan stage
- Break work into todo tasks; add final self-review task
Renamed: formerly
cook— now/feature-implement. The old name no longer resolves as a slash command.
feature-implement vs plan-execute:
feature-implementtakes an idea/feature description and goes idea → research → plan (created here) → shipped. Use/plan-executeinstead when a plan file already exists and you only need disciplined phase-by-phase execution + commit. feature-implement owns the front of the pipeline (research + planning); plan-execute owns the back (phase gates + auto-commit +--parallel/--approval/--testsflags).
Standalone Mode Pipeline (skip entirely if invoked inside a workflow)
MANDATORY — standalone
/feature-implementonly. When invoked OUTSIDE a workflow, wrap the core spine in this quality loop. Detect an active workflow viaTaskListFIRST: if a parent[Workflow]row exists, SKIP this section — the surrounding workflow already sequences plan/review/why-review around this skill (e.g.workflow-featurewraps feature-implement with exactly these steps).Create these as
TaskCreatetasks up front, in order, then execute them:
/spec— spec-driven, BEFORE any plan or code. Create or update the tech-free 8-section Feature Spec underdocs/specs/so the plan and implementation satisfy an agreed contract, not chat memory. Decide the case from evidence: net-new capability with no code yet →/spec [mode=draft](provisional,Evidence: TBD); enhancement to an already-documented feature →/spec [mode=update]; behavior/contract change to existing spec →/spec [mode=amend]; buggy/undocumented area that now warrants a spec →/spec [mode=init]. If a governing spec already exists and fully covers this change, recordSpec verified current — no changewithfile:lineevidence and proceed. Skip ONLY in fast mode (ALL Default Mode Policy trivial-task conditions met — no behavior/contract change); record the skip reason. Decide the case explicitly — skip only the authoring, never the decision./plan— author the implementation plan from the spec. feature-implement's Comprehensive Planning phase (Step 2) satisfies this; emit a reviewable plan artifact underplans/. Map each plan phase's## Test Specificationsto the spec's §8TC-{FEATURE}-{NNN}IDs./plan-review— recursively review/validate the plan; fix validated findings that block the current severity bar before implementing.- Proceed — execute the core implementation spine (research already done → implement → test → review → docs).
/spec [mode=sync]— spec-driven closure. Reconcile the spec's §8TC-{FEATURE}-{NNN}↔ integration tests and refreshEvidence: TBDmarkers to realfile:linenow that code exists. Run/spec [mode=tests]first if the implementation introduced behavior not yet captured as a test case. Skip only when step 1 was skipped (fast-mode trivial, no spec touched)./changes-review— review the diff before commit./why-review— review rationale and change quality of the implementation.
First Principle — Easy to Change
The success metric of every coding decision is future change cost. DRY, SRP, abstraction, design patterns, naming, layering, tests — every technique exists to serve one goal: making the next change cheaper.
When evaluating code, refactor, test, or abstraction, ask: does this make the next change cheaper or more expensive?
- Reject "best practices" raising change cost (premature abstraction, speculative generality, leaky indirection, ceremony without payoff).
- Name real enemies in findings: coupling, hidden state, duplicated knowledge, unclear intent, irreversible decisions exposed too early.
- Simpler design easy to change beats sophisticated design that isn't.
Apply this lens before invoking any specific rule, pattern, or checklist below — if a downstream rule would raise change cost, this principle wins.
Default Mode Policy
Default mode HARD (full rigor). Every section below — deep research, mandatory
/plan, fullcode-reviewerreview, mandatory tests, mandatory/docs-update— applies by default.Opt out to fast mode ONLY when ALL true (task genuinely trivial):
- Single-file edit, ≤30 lines changed
- No design choice (only one reasonable approach)
- No cross-service impact, no contract change, no new dependency
- No new pattern — follows existing codebase pattern
- Existing tests cover change OR change non-functional (typo, comment, log message)
Any condition fails → use full protocol below. When in doubt, default hard. Skipping review/tests on non-trivial change ships bugs.
Fast mode skips (and only skips): researcher subagent phase (direct grep instead), mandatory
code-reviewerreview (self-review only), separate test phase (verify inline). Does NOT skip/planstep, test execution,/docs-updatetriage.
Backend Context (if applicable)
When task involves backend changes, read these directly before implementing:
- CQRS commands/queries, validation, repositories, entity events:
docs/project-reference/backend-patterns-reference.md - Entity catalog, relationships, cross-service sync:
docs/project-reference/domain-entities-reference.md - Repository type (service-specific): when the project declares a per-service repository abstraction (
backendServices.serviceRepositoriesindocs/project-config.json), use that repository type for the service — NEVER the generic root repository base.
Frontend/UI Context (if applicable)
When task involves frontend or UI changes:
- Component patterns:
docs/project-reference/frontend-patterns-reference.md - Styling/BEM guide:
docs/project-reference/scss-styling-guide.md - Design system tokens:
docs/project-reference/design-system/README.md
Ultrathink plan and implement these tasks with maximum verification:
Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act.
$ARGUMENTS
Mode: Extra research, detailed planning, mandatory reviews.
Workflow
0. Goal Contract Read (BEFORE implementation)
- Resolve the active Goal Contract per
SYNC:goal-contract-satisfaction-loop: active plangoal.md→plans/goals/{YYMMDD-HHmm}-{slug}/goal.md→ create from the current request via.claude/templates/goal-contract-template.md. - Read the saved success criteria BEFORE any code change — implementation serves the saved criteria, not chat memory.
- After implementation and verification, append an Iteration Log entry to the goal file: result, evidence references (
file:line, command output), remaining gaps mapped to criteria.
1. Deep Research Phase
- Launch 2-3
researchersubagents in parallel covering:- Technical approach validation
- Edge cases, failure modes
- Security implications
- Performance considerations
- Use
/investigatefor comprehensive codebase analysis - Research reports max 150 lines each
- External Memory: Write all research to
.ai/workspace/analysis/{task-name}.analysis.md. Re-read ENTIRE file before planning. - Pre-Implementation Trace Gate: For bugfix, failed verification, stale/incorrect final output, regression, or behavior-changing fix plans, MUST ATTENTION confirm the plan/referenced analysis includes
Debugger Trace: End -> Start, all feeder paths, hypothesis matrix, owning fix layer, and forward convergence proof. If missing, STOP and produce the missing-trace list before editing.
After implementing, run
python .claude/scripts/code_graph connections <file> --jsonon modified files; verify no related files need updates.
Graph-Trace Before Implementation
When graph DB available, BEFORE writing code, trace blast radius:
python .claude/scripts/code_graph trace <file> --direction both --json— what calls this code AND what it triggerspython .claude/scripts/code_graph trace <file> --direction downstream --json— all downstream consumers- Prevents breaking implicit dependencies (bus message consumers, event handlers)
2. Comprehensive Planning
- Use
plannersubagent with all research reports - Create full plan directory:
plan.md— overview with risk assessmentphase-XX-*.md— detailed phase files- Success criteria per phase
- Rollback strategy
3. Verified Implementation
- Implement one phase at a time
- After each phase:
- Run type-check, compile
- Run relevant tests
- Self-review before proceeding
Batch Checkpoint (Large Plans)
For plans with 10+ tasks, execute in batches with human review:
- Execute batch — Complete next 3 tasks (or user-specified size)
- Report — Show implementation, verification output, any concerns
- Wait — Say "Ready for feedback" and STOP. Do NOT continue automatically.
- Apply feedback — Incorporate changes, execute next batch
- Repeat until all tasks complete
4. Mandatory Testing
- Use
testersubagent for full test coverage - Write tests for:
- Happy path scenarios
- Edge cases from research
- Error handling paths
- NO mocks or fake data
- Repeat until all tests pass
5. Mandatory Code Review
- Use
code-reviewersubagent - Apply the canonical review policy: Round 1 fixes every validated finding; Round 2+ fixes only validated CRITICAL/HIGH/MEDIUM findings, while LOW-only findings are recorded as deferred and do not reopen the loop.
- Failed binary gates (tests, required artifacts, security must-fix, parity) block at every round and are never relabeled LOW.
- Re-run tests after fixes and start a fresh full review after every fix cycle.
- Stop when the current round's severity bar is clear; cap at three rounds and escalate repeated/no-progress CRITICAL/HIGH/MEDIUM findings rather than looping open-ended.
6. Documentation Update
- Use
docs-managerto update relevant docs - Use
project-managerto update project status - Record architectural decisions
7. Final Report
- Summary of all changes
- Test coverage metrics
- Security considerations addressed
- Unresolved questions (if any)
- Ask user to review and approve
When to Use
- Critical production features
- Security-sensitive changes
- Public API modifications
- Database schema changes
- Cross-service integrations
Quality Gates
| Gate | Criteria |
|---|---|
| Research | 2+ researcher reports |
| Planning | Full plan directory |
| Tests | All pass, no mocks |
| Review | No blocking findings under the current severity bar; deferred LOWs listed |
| Docs | Updated if needed |
Next Steps (Standalone: MUST ATTENTION ask user via AskUserQuestion. Skip if inside workflow.)
MANDATORY IMPORTANT MUST ATTENTION — NO EXCEPTIONS: If this skill was called outside a workflow, MUST ATTENTION use
AskUserQuestionto present these options. Do NOT skip because task seems "simple" or "obvious" — user decides:
- "Proceed with full workflow (Recommended)" — Detect best workflow to continue from here (feature implemented). Ensures review, testing, docs steps aren't skipped.
- "/code-simplifier" — Simplify and clean up implementation
- "/workflow-review-changes" — Review changes before commit
- "Skip, continue manually" — user decides
If already inside a workflow, skip — workflow handles sequencing.
[IMPORTANT] Use
TaskCreateto break ALL work into small tasks BEFORE starting — including tasks for each file read. Prevents context loss from long files. For simple tasks, MUST ATTENTION ask user whether to skip.
docs/project-reference/domain-entities-reference.md— Domain entity catalog, relationships, cross-service sync (read when task involves business entities/models)docs/specs/— Test specifications by module (read existing TCs; generate/update via/spec [mode=tests]after implementation)
End-to-Start Debugger Trace — For non-trivial bugs, failed verification, regression fixes, behavior-changing code, or unclear code flow, start from the observed final state and walk backward before proposing a fix.
- Frame 0: observed end state — Name the exact user-visible output, failing assertion, log line, persisted value, API response, rendered UI, or aggregate bucket. Record the reader/query/renderer that produced it with
file:lineevidence.- Walk backward one hop at a time — Trace final reader -> projection/cache/storage -> writer -> consumer/handler/job -> producer/caller -> original trigger. At every hop record: input, transformation, output, owner, and evidence.
- Enumerate all feeder paths — Find every upstream producer/caller/event/job that can write into the final path, including retry, async, cache, background, and alternate UI/API paths. Mark each path verified, ruled out, or still unknown.
- Build the hypothesis matrix — For each plausible cause, list evidence for, evidence against, how to reproduce/verify, blast radius, and status (
primary,contributing,ruled out,latent). Do not fix until competing causes are explicitly resolved or bounded.- Choose the owning fix layer — Identify the invariant owner and the lowest shared point that protects all downstream consumers. A fix at the symptom site is rejected unless the symptom site owns the invariant.
- Prove convergence forward — After choosing the fix, walk start -> end again and show how the corrected state reaches the observed final output. Map each root cause to a fix part and each fix part to a test/proof.
BLOCKED until: final state named · backward trace written · all feeder paths enumerated · hypothesis matrix completed · owning fix layer justified · forward convergence proof mapped to tests.
NEVER: Start at the first suspicious code path. Collapse multiple producers into one "flow". Treat duplicate symptoms as duplicate records without proving the read model. Skip ruled-out hypotheses.
Source/test drift check. For coding, fix, debug, investigation, test, or review work: when source behavior changes, inspect affected unit/integration/E2E tests and decide from evidence whether tests should change to match intended behavior or the source change is an unintended bug to fix. Do not write tests for migration code; schema/data migrations are one-time execution paths, not core application logic.
AI Mistake Prevention — Failure modes to avoid on every task:
Re-read files after context changes. Context compaction, resume, or long-running work can make memory stale; verify current files before acting. Verify generated content against source evidence. AI hallucinates APIs, names, claims, and document facts. Check the relevant source before documenting or referencing. Check downstream references before deleting or renaming. Removing an artifact can stale docs, generated mirrors, configs, and callers; map references first. Trace the full impact chain after edits. Changing a definition can miss derived outputs and consumers. Follow the affected chain before declaring done. Verify ALL affected outputs, not just the first. One green check is not all green checks; validate every output surface the change can affect. Assume existing values are intentional — ask WHY before changing OR flagging one as a defect. Before changing or reporting a constant, limit, flag, cutoff, wording, or pattern, read nearby context and history, the CALLER's ordering, and 2+ sibling call sites of the same convention. A doc stating WHAT without WHY is missing rationale, not proof of a missing guard. Surface ambiguity before acting — don't pick silently. Multiple valid interpretations require an explicit question or stated assumption with risk. Assert the outcome your system owns, not the intermediate state your infrastructure owns. When verifying async work, assert the final business state — never the delivery/retry bookkeeping held in shared infrastructure that any co-running process can write. Such a check passes when run alone and flakes the moment anything else shares that infrastructure. Keep shared guidance role-relevant. Universal guidance must help every receiving skill or agent; code-specific obligations belong only in code-specific protocols.
UI System Context — For ANY task touching
.ts,.html,.scss, or.cssfiles:MUST ATTENTION READ before implementing:
docs/project-reference/frontend-patterns-reference.md— component base classes, stores, formsdocs/project-reference/scss-styling-guide.md— BEM methodology, SCSS variables, mixins, responsivedocs/project-reference/design-system/README.md— design tokens, component inventory, iconsReference
docs/project-config.jsonfor project-specific paths.
Graph-Assisted Investigation — MANDATORY when
.code-graph/graph.dbexists.HARD-GATE: MUST ATTENTION run at least ONE graph command on key files before concluding any investigation.
Pattern: Grep finds files →
trace --direction bothreveals full system flow → Grep verifies details
Task Minimum Graph Action Investigation trace --direction bothon 2-3 entry filesFix/Debug callers_ofon buggy function +tests_forFeature/Enhancement connectionson files to be modifiedCode Review tests_foron changed functionsBlast Radius trace --direction downstreamCLI:
python .claude/scripts/code_graph {command} --json. Use--node-mode filefirst (10-30x less noise), then--node-mode functionfor detail.
Nested Task Expansion Contract — For workflow-step invocation, the
[Workflow] ...row is only a parent container; the child skill still creates visible phase tasks.
- Call
TaskListfirst. If a matching active parent workflow row exists, setnested=trueand recordparentTaskId; otherwise run standalone.- Create one task per declared phase before phase work. When nested, prefix subjects
[N.M] /skill-name — phase.- When nested, link the parent with
TaskUpdate(parentTaskId, addBlockedBy: [childIds]).- Orchestrators must pre-expand a child skill's phase list and link the workflow row before invoking that child skill or sub-agent.
- Mark exactly one child
in_progressbefore work andcompletedimmediately after evidence is written.- Complete the parent only after all child tasks are completed or explicitly cancelled with reason.
Blocked until:
TaskListdone, child phases created, parent linked when nested, first child markedin_progress.
Project Reference Docs Gate (static JIT) — Run after task-tracking bootstrap and immediately before target/source file reads, grep, edits, tests, or analysis. Project docs override generic framework assumptions; hooks may remind or accelerate this gate, but never prove that it ran.
- Identify scope: file types, domain area, and operation.
- Read
docs/project-config.jsonfirst — the project's machine-readable map. It is the single source of truth for THIS repo (modules/paths, framework + search keywords, test/E2E/integration run-commands, design system, architecture rules, workflow patterns); ground exact paths, run-commands, and conventions on it before investigating, planning, or coding — never assume framework defaults (CLAUDE.md+ reference docs are derived from it). If it — or the docs index,lessons.md,CLAUDE.md,AGENTS.md, or any required reference doc — is missing or stale, auto-run/project-initor the narrow route (/project-config,/docs-init,/scan-all,/scan --target=<key>,/claude-md-init) first; if Codex mirrors orAGENTS.mdare stale, ask the user to run/sync-codex(never auto-run it).- Required docs by trigger: always
docs/project-reference/lessons.md; doc lookupdocs-index-reference.md; reviewcode-review-rules.md; backend/CQRS/APIbackend-patterns-reference.md; domain/entitydomain-entities-reference.md; frontend/UIfrontend-patterns-reference.md; styles/designscss-styling-guide.md+design-system/design-system-canonical.md; integration testsintegration-test-reference.md; E2Ee2e-test-reference.md; feature docs/specsfeature-spec-reference.md+spec-system-reference.md+spec-principles.md; behavior/public-contract/spec-test-code syncworkflow-spec-test-code-cycle-reference.md; derived spec index/ERD/reimplementation guidesspec-system-reference.md+ source Feature Specs underdocs/specs/; architecture/new areaproject-structure-reference.md.- Read every required doc, then before target work state:
Reference docs read: ... | Not applicable: .... After compaction, resume, delegation, or a material context change, repeat the route and restate the set; prior conversation and hook output are not proof of current loading.Ready when: scope evaluated,
docs/project-config.jsonconsulted, required docs checked/read or setup route completed,lessons.mdconfirmed, citation emitted.
Task Tracking & External Report Persistence — Bootstrap this before execution; then run project-reference doc prefetch before target/source work.
- Create a small task breakdown before target file reads, grep, edits, or analysis. On context loss, inspect the current task list first.
- Mark one task
in_progressbefore work andcompletedimmediately after evidence; never batch transitions.- For plan/review work, create
plans/reports/{skill}-{YYMMDD}-{HHmm}-{slug}.mdbefore first finding.- Append findings after each file/section/decision and synthesize from the report file at the end.
- Final output cites
Full report: plans/reports/{filename}.Blocked until: task breakdown exists, report path declared for plan/review work, first finding persisted before the next finding.
Critical Thinking Mindset — Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence >80% to act. Anti-hallucination: Never present guess as fact — cite sources for every claim, admit uncertainty freely, self-check output for errors, cross-reference independently, stay skeptical of own confidence — certainty without evidence root of all hallucination.
Understand Code First — HARD-GATE: Do NOT write, plan, or fix until you READ existing code.
- Search 3+ similar patterns (
grep/glob) — citefile:lineevidence- Read existing files in target area — understand structure, base classes, conventions
- Run
python .claude/scripts/code_graph trace <file> --direction both --jsonwhen.code-graph/graph.dbexists- Map dependencies via
connectionsorcallers_of— know what depends on your target- Write investigation to
.ai/workspace/analysis/for non-trivial tasks (3+ files)- Re-read analysis file before implementing — never work from memory alone. — why: long context drifts from the file; the file is ground truth
- NEVER invent new patterns when existing ones work — match exactly or document deviation. — why: divergent patterns fragment the codebase and slow every future reader
BLOCKED until:
- [ ]Read target files- [ ]Grep 3+ patterns- [ ]Graph trace (if graph.db exists)- [ ]Assumptions verified with evidence
Plan Quality — Every plan phase MUST ATTENTION include test specifications.
- Add
## Test Specificationssection with TC-{FEATURE}-{NNN} IDs to every phase file- Map every functional requirement to ≥1 TC (or explicit
TBDwith rationale)- TC IDs follow
TC-{FEATURE}-{NNN}format — reference by ID, never embed full content- Before any new workflow step: call
TaskListand re-read the phase file- On context compaction: call
TaskListFIRST — never create duplicate tasks- Verify TC satisfaction per phase before marking complete (evidence must be
file:line, not TBD)- Purpose-oriented naming: For every planned public or cross-layer contract, port, interface, module, or adapter, name the consumer-visible capability or domain purpose; keep provider, framework, and transport names in concrete implementations (
IStorage/Storage→AzureBlobStorage). — why: a contract name should survive an implementation swap.- Contract-fit gate: Check the proposed name against its callers and all implementations; use a narrower purpose name when a broad name overpromises (
IObjectStoreorDocumentStoreinstead ofIStoragewhen the behavior is narrower). — why: abstraction names must describe the actual contract, not hide a mismatch.- No speculative abstraction: Plan an interface or port only when a real boundary, substitution need, or multiple meaningful implementations justifies it; keep a concrete type when it is the honest contract. — why: an unnecessary abstraction adds indirection and a second name without reducing change cost.
- Language convention: Preserve the repository's naming syntax (
Iprefix where the language/project uses it); never forceIorInterfacemarkers across languages. — why: semantic purpose is portable, syntax is not.- Foundation obligations — when the plan CREATES or CHANGES how the project is built, run, tested, or checked (build or CI configuration, test harness, containerization, toolchain/dependency management, module boundaries, quality tooling): run
SYNC:engineering-foundation-gate— its seven dimensions F1-F7, the four profile axes and the warranting matrix are in.claude/docs/engineering-foundation-catalog.md, which the plan reads directly when no carrier of that gate ran upstream — and carry every dimension it marks warranted into the plan as an explicit phase with acceptance criteria — never as an assumption that someone handles it later. Record each dimension deliberately skipped, with the reason. — why: a plan that stands up a foundation and silently omits a warranted dimension makes that omission permanent and invisible; foundations cost near nothing at creation and a great deal to retrofit.Mode: TDD-first → reference existing TCs with
Evidence: TBD. Implement-first → use TBD →/spec [mode=tests]fills after.
[BLOCKING] Design distinctiveness gate (
DD-1–DD-8) — binds on ANY task that designs, plans, mocks up, implements, or reviews a user-facing visual surface. Deep catalog:.claude/docs/design-knowledge.md. Cite findings asDD-<clause>+file:line.Precedence (resolve in this order, never silently): the brief's own stated visual direction WINS outright — including when it asks for one of the
DD-4tells. Then the project's design-system / SCSS / frontend-pattern docs and accepted ADRs — a house style IS an intentional identity, and re-deciding it per feature is the incoherence this gate prevents. Then these clauses. A genuine conflict is SURFACED to the user with both sides, NEVER resolved silently.Relationship to
UI-1.1–UI-9.4: a different question, no overlap — the 40 clauses ask "is this usable, accessible, consistent?" (a measurable floor); this gate asks "is this THIS product's interface, or the one any generator would emit for any brief?". A surface can pass all 40 clauses and still be a template. BOTH bind; where they touch (type scale, colour, motion timing) the clause sets the floor and this gate picks the value.
DD-1Ground it in the subject matter. Before designing, name the concrete subject, the audience, and the design's primary job — and CONFIRM with the user when the brief is silent. Distinctive choices come FROM the subject's industry, materials and vernacular; they are never taste applied on top. Test: if the palette, type and layout would fit a different product unchanged, there is no identity yet.DD-2Every choice carries a WHY. "It's common", "it's clean", "users expect it" are not reasons. A decision with no articulable reason is a default that arrived unnoticed. Defaults hide in what feels like infrastructure — typography, navigation, data display, and TOKEN NAMES. Token-name test: someone reading only your CSS variables should be able to guess what product this is (--ink/--parchmentevoke a world;--gray-700/--surface-2evoke a template).DD-3Two passes, and the review pass is mandatory. (1a) Write a compact design plan — Colour (4–6 named hex values) · Type (families + roles + scale) · Layout (one-sentence prose + ASCII wireframes to compare alternatives, including alignment: left/centre/justified) · Principles (what makes THIS page unique). (1b) BLOCKING generic test — before any code: work through a similar prompt and see whether you arrive somewhere similar; any part that reads like the generic default for any comparable page rather than a choice for THIS brief gets REVISED, and you state what you changed and why. Then (2a) build the REVISED plan, (2b) critique. — why: writing a plan and going straight to code reproduces the default, because the plan came from the same patterns the code will.DD-4Audit every FREE axis against the generated-design tell catalog ([model-knowledge], calibration not prohibition — each trait is legitimate for SOME brief): T1 cream#F4F1EA+ high-contrast serif + terracotta near#D97757(Anthropic's own interaction accent — on a user's brief it reads specifically as a tell) · T2 near-black + one acid-green/vermilion accent · T3 broadsheet hairline-rule pastiche, zero radius, dense columns · T4 the SaaS-card kit: identical rounded cards, ONE radius regardless of hierarchy, the samergba(0,0,0,.1)shadow under each, gradient washes as decoration · T5 template chrome whatever the subject: tracked-out ALL-CAPS eyebrow above every heading, meta strings joined with middle dots (A · B · C),WORD — fragmentlabels with a spaced em dash, tinted near-black (#0B0B0B/#111) standing in for black, monospace for small data labels,→appended to link/button text. A match is a HYPOTHESIS about a missed decision, never a defect — promote it only by naming the axis, that the brief left it free, and what the subject suggested instead.DD-5Typography carries the personality. One family, or two CLEARLY distinct ones — you do NOT need separate display and body faces. Choose deliberately, not the default you would reach for on any project. Set a real scale with intentional weights, widths and spacing. When type is a headline it is an ACTIVE part of the design, not a neutral delivery vehicle. Measure under ~80 characters; serifs tolerate slightly longer lines and want slightly more line-height than sans at the same size. Hierarchy needs weight/tracking/opacity, not size alone. Avoid the three commonest tells: accenting a single word in a headline (italic/bold/colour) · ALL CAPS labels · an eyebrow label that names the section the heading already names.DD-6Structure is information, not decoration. Outlines, borders, numbering, eyebrows, dividers and labels must encode something about the content. Before adding numbered markers (01 / 02 / 03), check the content really IS a sequence — a stepped process, timeline or ranking. For every device ask: what does this tell the reader that whitespace would not? Nothing → cut it. Hero: open with the most characteristic thing in the subject's world, in whatever form fits (headline, image, animation, live demo, interactive moment) — big-number-plus-small-label-plus-gradient is the DEFAULT treatment, so use it only when it is genuinely best here. Composition: rhythm over monotone (same card size, same gap, same density everywhere is the sound of no one deciding); proportions must say something you can articulate; one dominant focal point.DD-7Motion sparingly and deliberately. Non-user-triggered motion draws attention ONLY. One orchestrated moment — a single page-load sequence or one reveal — lands better than scattered effects; fade-and-slide-up entrances on each section and hover transitions on every card are the generic default and read as generated. Motion that ANSWERS a person's action (opening, expanding, confirming) is welcome when it shows what changed. Honourprefers-reduced-motion.DD-8Spend boldness once, then remove one accessory. Let ONE element be the memorable thing and keep everything around it quiet and disciplined; cut any decoration that does not serve the brief. Critique the BUILT page, not just the plan — composition, craft (density is a decision, not a constant), content coherence, and CSS honesty (negative margins undoing a parent's padding,calc()values that exist only as workarounds, absolute positioning to escape layout flow are lies; the correct answer is always simpler than the hack). Take screenshots to review where the environment supports it — a picture is worth 1000 tokens. Then ask "if they said this lacks craft, what would they point to?" and fix that. Build the quality floor in silently — responsive, visible keyboard focus, reduced-motion respected, measured contrast, tokens never raw hex or magic numbers — and watch CSS selector specificity, where a type-based selector (.section) and an element-based one (.cta) most often cancel each other's padding/margin.Memory: vary between briefs — light and dark, families, direction. NEVER converge on the same choice across generations (Space Grotesk, for example). Where the project already has a design system, tokens, or an
interface-system.md, ADOPT and record it rather than re-deciding; write back any pattern used 2+ times with measurements worth remembering.Skip ONLY when the change has NO user-facing visual surface (backend-only, tooling, docs) — state that reason explicitly so the skip is auditable, not an omission.
Words are design content, not decoration — binds whenever a task authors, changes, or reviews user-visible strings (labels, CTAs, headings, empty/error/loading text, toasts, placeholder content). Deep detail:
.claude/docs/design-knowledge.md§8. Copy makes a design feel as templated as the visuals do.Before writing anything, ask what the design needs to SAY and how it can best be said to help the person navigate the experience. Then:
- Write from the end user's perspective. Name things by what users will understand in simple language, not by how the system is built — a user manages notifications, not webhook config. Describe what something is or does in plain terms rather than selling it. Being specific and legible to a new user ALWAYS beats being clever.
- Active voice by default. A CTA says exactly what happens when it is used: "Save changes", NEVER "Submit".
- One name per action, across the whole flow. The button that says Publish produces a toast that says Published. The vocabulary of an interface is the signposting for someone navigating the product — cohesion and consistency are how people learn their way around.
- Failure and emptiness give DIRECTION, not mood. Explain what went wrong and how to fix it, in the interface's voice rather than a person's. Errors do NOT apologize, and are NEVER vague about what happened. An empty screen is an invitation to act.
- Conversational tone, one job per element. Plain verbs, sentence case, no filler, tone matched to the brand and the audience; let each written element do exactly one job.
- Real content, never lorem. When the brief supplies no copy, write plausible strings for the ACTUAL subject. Coherence check — read every visible string as a user would, checking for truth, not typos: could a real person at a real company be looking at exactly this data right now, or does the page title belong to one product, the body to another, and the sidebar metrics to a third? A beautifully designed interface with nonsensical content is a movie set with no script.
Skip ONLY when the change surfaces no user-visible text — state that explicitly.
Front-End Design Review Checklist — the EXECUTABLE review protocol for any artifact carrying a user-facing front-end surface. Full catalog (
A1…Q, ~130 checks with failure signals and default severities):.claude/docs/design-review-checklist.md. This gate carries the protocol and the triage pass; the file carries the checks.Applies when — and ONLY when — the change, plan, or artifact carries a user-facing front-end surface. A back-end-only diff, a doc edit, or a config change is
N/A: state that once and move on. NEVER run a UI review on a non-UI change to manufacture coverage. When it DOES apply, MUST ATTENTION READ.claude/docs/design-review-checklist.mdand work its sections — a review that cites a check ID wi
…(truncated)