design-compounder

name	design-compounder
description	Use when orchestrator has reconciled a design sprint outcome and queued the feature id in compound_pending_feature_ids.

Design Compounder

Placement

This is a nested child under frontend-design; its path is frontend-design/design-compounder/, and the router selects it before standalone use.

You are the learning phase of the design harness. Your job is to decide what, if anything, from the just-concluded sprint should become durable cross-sprint knowledge.

Compounding is explicit and non-runnable. It does not reopen any phase. It does not claim the runnable sprint slot. It extracts only what has artifact-linked provenance — not what seemed good in the conversation.

Worker Dispatch Contract

• Run in a fresh worker context after orchestrator. Do not fold compounding into state reconciliation.
• Only the orchestrator may spawn workers. This worker must not spawn another worker.
• Tool lane: read sprint evidence, write .agents-stack/insights/session-log.md only when durable residue survives with provenance, optionally patch .agents-stack/reference/design.md and scoped .agents-stack/reference/*, and clear the queue entry in .agents-stack/tracked-work.json. No product-code edits, no .agents-stack/*/status.json rewrites, no archive moves.
• Not parallel-safe against another worker touching .agents-stack/insights/session-log.md or .agents-stack/reference/design.md. Process one queued feature at a time.
• Dispatch framing is non-authoritative. Verify the queued feature against .agents-stack/tracked-work.json before writing.

Required Reads

Before writing anything:

1. AGENTS.md
2. .agents-stack/tracked-work.json — confirm the feature is in compound_pending_feature_ids
3. .agents-stack/insights/session-log.md — current durable learning baseline
4. .agents-stack/reference/design.md — current stable reference
5. Sprint decisive evidence: design-qa.md, design-handoff.md, design.md

What Qualifies as Durable Learning

Extract only lessons that meet all three criteria:

1. Decisive — drawn from design-qa.md verdict, accepted design.md criteria, or confirmed design-handoff.md evidence, not from the conversation or from plausible inferences.
2. Artifact-linked — can cite the exact sprint file and path that proves the lesson.
3. Cross-sprint valuable — benefits a future sprint, not just a record of what this sprint did.

Design-specific durable lessons worth capturing

Category	Example worth capturing
Token decisions	"Project uses #1A1A2E as the primary dark surface; oklch derivations for accents work better than inventing new colors."
Font choices	"Libre Baskerville at 600 weight reads well at 32px+ for slide headings; below 24px it becomes too heavy."
Component patterns	"Card hover state: transform: translateY(-2px) + shadow lift proved more legible than color-fill transitions at the project's density."
Scaffold insight	"Deck projects at 1920×1080 with scale() wrapper lose crisp text below 0.6x zoom; prefer SVG for diagrams."
Anti-pattern confirmed	"Left-border accent card was proposed in sprint DESIGN-002 and flagged by review as AI slop — reject it in all future sprints."
Accessibility discovery	"Project's semantic primary blue (#2563EB on white) only achieves 4.4:1 — use the +10% darker variant (#1D4ED8) for body text."
Variation strategy finding	"Color treatment and layout variations got the most human attention; typography-only variations were consistently ignored."
Review failure pattern	"React const styles = {} naming collision broke the Tweaks panel in DESIGN-001 and DESIGN-002; always use component-prefixed names."

What is not durable learning

• "The artifact looked good." — no provenance, no future value
• "We used Tailwind." — architecture fact, not a lesson
• Routine implementation steps that apply to every sprint
• Observations that contradict design-qa.md evidence
• Chat-only conclusions with no artifact path

Decision: Extract or Skip

Before writing .agents-stack/insights/session-log.md, decide explicitly:

Extract when: at least one lesson qualifies under all three criteria above.

Skip deliberately when: the sprint produced no lessons that survive the criteria, or all apparent lessons lack decisive artifact provenance. Record the skip decision in .agents-stack/insights/session-log.md as a one-line dated note: [SPRINT-ID] Deliberately skipped — no durable design residue with artifact provenance found.

Skipping is not a failure. Silently inventing lessons is.

.agents-stack/insights/session-log.md Entry Format

Append to .agents-stack/insights/session-log.md. Do not overwrite existing entries.

## [SPRINT-ID] <short lesson title> — <ISO date>
- **Category**: token | typography | component | scaffold | anti-pattern | accessibility | variation-strategy | process
- **Lesson**: [one clear sentence stating the durable learning]
- **Evidence**: `.agents-stack/<sprint-id>/design-qa.md` — [exact finding id or section name]
- **Applies to**: all future sprints | sprints using [specific output type] | projects using [specific design system]
- **Provenance**: [link to decisive artifact: design-qa.md#DQ-001, design.md#AC-002, etc.]

Multiple distinct lessons from one sprint each get their own entry.

.agents-stack/reference/design.md Update

Update .agents-stack/reference/design.md only when the lesson is stable current truth — meaning it describes how the project works now, not an observation from one sprint.

Examples that justify a reference update:

• A token value was confirmed as the canonical choice and should be documented for all future builders
• A component pattern was ratified and should be the default going forward
• A known constraint (contrast issue, font limitation) applies to the whole project

Examples that do not justify a reference update:

• A lesson that only applies to slide decks in this one sprint
• A finding that may change when the design system evolves
• An advisory observation that hasn't been ratified

When updating .agents-stack/reference/design.md, make a precise addition or edit — do not rewrite the whole file. Note the sprint id and evidence path in a comment or footnote.

.agents-stack/reference/* Scoped Page

Create a scoped record page only when:

• Durable discussion residue is too detailed for a .agents-stack/insights/session-log.md entry
• The content is not stable enough for .agents-stack/reference/design.md
• The feature already exists in .agents-stack/tracked-work.json with a record_paths field

Register the path in the feature's record_paths in tracked-work.json. Do not create a record as a substitute for .agents-stack/insights/session-log.md or as a second archive.

Queue Clearance

After writing (or deliberately skipping), remove the feature id from compound_pending_feature_ids in .agents-stack/tracked-work.json. This is the only mandatory write — even a skip requires it.

Done Definition

This phase is complete when:

• The queue entry is cleared from compound_pending_feature_ids
• .agents-stack/insights/session-log.md either has new entries with artifact-linked provenance, or records a dated deliberate-skip note
• Any .agents-stack/reference/design.md update is a precise, stable-truth addition
• No phase is reopened, no runnable sprint slot is claimed