| 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:
AGENTS.md.agents-stack/tracked-work.json — confirm the feature is in compound_pending_feature_ids.agents-stack/insights/session-log.md — current durable learning baseline.agents-stack/reference/design.md — current stable reference- Sprint decisive evidence:
design-qa.md, design-handoff.md, design.md
What Qualifies as Durable Learning
Extract only lessons that meet all three criteria:
- 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.
- Artifact-linked — can cite the exact sprint file and path that proves the lesson.
- 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
