| name | workflows-compound |
| description | Capture learnings from the workflow into reusable documentation. Stage 7 of the development workflow. |
| argument-hint | [optional focus area] |
| user-invocable | true |
Capture learnings from the current workflow: $ARGUMENTS
Purpose
You are executing Stage 7 (Compound) of the development workflow. Implementation is reviewed and revised. Your job is to extract reusable learnings from this workflow and persist them so future workflows benefit. You are NOT writing code — you are documenting what was learned.
Pre-Conditions
Before starting, verify:
.workflow/state.json exists and currentStage is "compound"- Review has passed (check
stages.review.status is "completed")
- If revision happened, it's also completed
If pre-conditions are not met, report what's missing and halt.
Process
Step 1: Gather Evidence
Read all workflow artifacts:
- Workflow state:
.workflow/state.json — timeline, iterations, stage notes
- Sub-agent summaries:
.workflow/summaries/*.md — what was built
- Review report:
.workflow/review-report.md — what was found
- Spec and ADR: The original design documents
- Git log: What actually changed
git log --oneline --since="$(jq -r .startedAt .workflow/state.json)" -- .
Step 2: Extract Learnings
Identify three categories of learnings:
Solutions — Reusable patterns for solving specific problems:
- What problem was solved?
- What approach worked?
- What approach was tried and didn't work?
- What would you do differently next time?
Discoveries — Things learned about the codebase or domain:
- Unexpected behaviors encountered
- Undocumented constraints discovered
- Performance characteristics measured
Process — What worked or didn't in the workflow itself:
- Which stages were smooth vs. painful?
- Where did revision loops happen and why?
- What spec assumptions were wrong?
Step 3: Write Solution Document
If a reusable solution was produced, write it to docs/solutions/:
# <Problem Title>
## Problem
[What problem this solves, in 2-3 sentences]
## Solution
[The approach that worked, with code references]
## Context
- Workflow: <id>
- Spec: <path>
- Date: <ISO date>
## Key Decisions
- [Decision 1]: [Why this choice was made]
- [Decision 2]: [Why this choice was made]
## What Didn't Work
- [Approach that was tried and abandoned, with brief explanation]
## Related
- [Links to specs, ADRs, or other solutions]
Step 4: Update Agent Memory
If significant patterns or discoveries should persist across sessions:
- Check existing memory files for related entries
- Update or add entries as appropriate
- Include fitness tags (HOT/WARM/COLD) per the DGM calibration rules
Step 5: Record and Handoff
-
Update workflow state (.workflow/state.json):
- Set
stages.compound.status to "completed"
- Set
stages.compound.completedAt to current ISO timestamp
- Set
stages.compound.artifacts.solution to the solution doc path (if created)
- Set
currentStage to "reflection"
- Update
updatedAt
-
Present the handoff:
COMPOUND COMPLETE
==================
Solutions captured: N
Discoveries: N
Process notes: N
Solution doc: <path or "none — no reusable pattern identified">
Next: Stage 8 - Reflection (/workflow-reflection)
What Makes a Good Learning
A learning is worth capturing if it meets ANY of these:
- It would save >30 minutes if encountered again
- It contradicts documentation or common assumptions
- It reveals a non-obvious interaction between components
- It's a pattern that applies beyond this specific feature
A learning is NOT worth capturing if:
- It's specific to this feature with no broader applicability
- It's already documented in the codebase or specs
- It's a trivial fix that anyone would find quickly
Anti-Patterns
- Do NOT capture every detail — focus on what's reusable
- Do NOT write vague learnings like "testing is important" — be specific
- Do NOT skip this stage because "nothing interesting happened" — every workflow teaches something
- Do NOT write code — this is a documentation stage
- Do NOT create solution docs for trivial changes — only for patterns worth reusing
