Compound: Learning Capture & Knowledge Promotion

0. No-op guard — before starting, check if compound already ran recently:

   LAST_COMPOUND=$(find "${HOME}/.claude/state/" -name ".claude-compound-done-*" -mmin -30 2>/dev/null | head -1)
   LAST_COMMIT=$(git log -1 --format=%ct 2>/dev/null || echo 0)
   MARKER_TIME=$(stat -c %Y "$LAST_COMPOUND" 2>/dev/null || echo 999999999)
   

   If LAST_COMPOUND exists AND LAST_COMMIT < MARKER_TIME (no new commits since last compound): → Report "Compound skipped — no new work since last run (marker: [timestamp])." and STOP. Otherwise proceed normally.

1. Review what was done — read PRD, recent changes, or conversation context

2. Identify learnings:

   • What worked well?
   • What didn't work or was surprising?
   • Were there any assumptions that turned out wrong?
   • Did any tool/pattern perform better or worse than expected?

3. Update session-learnings with key findings (use structured format — see Step 6)

4. Knowledge Promotion Chain — check if promotion is warranted:

   • Does this pattern repeat from previous session-learnings? → promote to docs/solutions/
   • Does this affect architecture? → propose an ADR in docs/architecture/decisions/
   • Does this suggest a workflow change? → propose CLAUDE.md update (ask user first)

   4b. System Update Loop (when compound identifies workflow failures):

   • If the failure was caused by missing/ambiguous agent instructions: → UPDATE the agent definition file directly (ask user first)
   • If the failure was caused by a missing enforcement hook: → PROPOSE a settings.json hook change (ask user first)
   • If the failure was caused by a skill gap: → UPDATE the skill file directly (ask user first)
   • Memory entries alone are NOT sufficient for systemic failures. Memory helps future conversations. System updates prevent future failures.
   • Log every system change in ~/.claude/evolution/workflow-changelog.md with date, what, why, source.

   4c. Feedback Capture (mine user corrections for learning signal): User corrections are the richest learning signal. Scan the conversation for:

   • Explicit corrections: "no", "don't", "stop", "instead", "not that", "wrong"
   • Approach rejections: "let's not", "that's not right", "try X instead"
   • Preference signals: "I prefer", "always use", "never do"

   For each correction found:

   1. Is it project-specific? → session-learnings
   2. Is it a general pattern applicable to other projects? → error-registry entry
   3. Did the model fail at something it should handle? → model-performance (mark first_try_success = false)
   4. Does it imply a missing rule or hook? → propose system update (4b)
   5. Does it record a failed approach? → add to error-registry approaches_that_failed

5. The Three Compound Questions:

   • "What was the hardest decision made here?"
   • "What alternatives were rejected, and why?"
   • "What are we least confident about?"

6. Structured Session Learnings — when updating session-learnings, use categorized format:

   ## Errors
   - [CATEGORY] description → fix applied
   Categories: ENV, LOGIC, CONFIG, DEPENDENCY, SECURITY, TEST, DEPLOY, PROOT, MERGE, PERFORMANCE
   
   ## Rules Generated
   - Rule text (category: CATEGORY)
   
   ## Model Performance
   - model_name: N/M tasks first-try success (note any upgrades/downgrades needed)
   
   ## Metrics
   - Total retries: N
   - Phases that caught bugs: [list]
   - Phase 5 duration: Ns
   

7. Cross-Project Promotion — check if learnings apply beyond the current project:

   a. Error registry update — ALWAYS write errors to the registry, even on first occurrence. You can't detect cross-project patterns without capturing data points from day one.

   • Read ~/.claude/evolution/error-registry.json
   • JSON safety: Before writing, validate the file parses correctly. If corrupt, restore from error-registry.json.bak (or create empty {"entries":[]} if no backup).
   • Create backup: copy current file to error-registry.json.bak before modifying.
   • Add or update entry with:

     {
       "pattern": "error message or symptom regex",
       "category": "ENV|LOGIC|CONFIG|...",
       "root_cause": "why it happens",
       "fix": "how to fix it",
       "auto_preventable": false,
       "prevention": "hook/rule that prevents it (if auto_preventable)",
       "approaches_that_failed": [
         { "approach": "what was tried", "why_bad": "why it didn't work" }
       ],
       "projects_seen": ["project-name"],
       "first_seen": "2026-03-14",
       "last_seen": "2026-03-14",
       "occurrences": 1
     }
     

   • If entry already exists for this pattern: increment occurrences, update last_seen, add project to projects_seen, merge any new approaches_that_failed
   • If pattern seen in 3+ projects and auto_preventable: false: flag for hook creation
   • Write to temp file first, validate JSON parses, then replace original

   b. Model performance update — ALWAYS record model performance, even on first session.

   • Use the record script (atomic, flock-serialized — do NOT hand-edit the JSON):

     bash ~/.claude/hooks/scripts/record-model-performance.sh <model> <task_type> <first_try_success>
     

     • model: sonnet | opus | haiku
     • task_type: free-form label (e.g., sprint_execution, verification, bug_fix, implementation, compound, file_scanning)
     • first_try_success: true | false
   • Source of truth: Read from sprint-executor return summaries (model_requested, first_try_success, task_types) and orchestrator metrics (sprint_model_performance). Don't guess — use the structured data. Call the script once per (model, task_type, outcome) triple.
   • Check adaptation thresholds using the evaluate script:

     bash ~/.claude/hooks/scripts/evaluate-model-performance.sh
     

     • Reports upgrade candidates (samples >= 10, success rate < 70%)
     • Reports downgrade candidates (samples >= 10, success rate >= 90%)
     • Reports watch list (samples >= 5, not yet at threshold)
   • If the evaluator emits proposals: surface them to the user with the rationale. User approves → document the change in ~/.claude/evolution/workflow-changelog.md and update the default model in the relevant agent frontmatter.

   c. Memory promotion — if a learning applies across all projects:

   • Write to ~/.claude/projects/-root/memory/ (use appropriate memory type: feedback, project, or reference)
   • Update MEMORY.md index
   • Only promote patterns confirmed across 2+ tasks (session-learnings) or 2+ projects (error-registry)

   d. Workflow changelog — if any system file was modified (CLAUDE.md, skill, agent, hook):

   • Append entry to ~/.claude/evolution/workflow-changelog.md with date, what, why, source

8. Session Postmortem (MANDATORY — ALWAYS run, never skip):

   This file is the foundation of trend analysis in /workflow-audit. Skipping it makes future audits blind. Never batch, never skip — one file per /compound invocation.

   How to write it:

   1. Get a timestamp: TS=$(date +%Y-%m-%d_%H%M)
   2. Determine project name from the current working directory basename
   3. Use the Write tool (not echo/cat) to create ~/.claude/evolution/session-postmortems/${TS}_${PROJECT_NAME}.md
   4. File content must follow the template below verbatim, filled in with real data from this session

   The filename includes HHmm so multiple /compound invocations on the same day produce distinct files. Do NOT overwrite existing files.

   Template to write:

   # Session Postmortem — [date] — [project]
   
   ## Summary
   - Tasks completed: N
   - Tasks blocked: N
   - Total retries: N
   - Models used: [list with task counts]
   
   ## Error Categories
   - [CATEGORY]: N occurrences
   
   ## Verification Gate Effectiveness
   - Gate that caught real bugs: [list]
   - Gates that always passed (may be redundant for this project): [list]
   
   ## Model Performance This Session
   | Model | Task Type | Attempts | 1st Try | Rate |
   |-------|-----------|----------|---------|------|
   
   ## Compound Actions Taken
   - [list of system updates, promotions, rules generated]
   
   ## Open Questions
   - [from Three Compound Questions]
   

9. Write completion marker so the compound-reminder hook knows compound ran:

   touch "${HOME}/.claude/state/.claude-compound-done-${CLAUDE_CODE_SESSION_ID:-${CLAUDE_SESSION_ID:-unknown}}"
   

10. Workflow Integrity Gate — if compound modified ANY workflow files (~/.claude/ — hooks, skills, agents, settings.json, CLAUDE.md), run the integrity test suite:

    bash ~/.claude/test-workflow-mods/run-tests.sh
    

    • If all tests pass: proceed to step 11
    • If any tests fail: fix the failures before continuing. The test suite validates that all hooks exist and are executable, settings.json registrations are correct and cross-referenced, CLAUDE.md documents all key concepts, agent/skill files have correct structure, and evolution infrastructure is intact.
    • This step is MANDATORY when workflow files were modified. Skip ONLY if no ~/.claude/ files were touched during this compound cycle.

11. If using git backup for ~/.claude/: suggest committing workflow changes

Quick Fix Micro-Compound

When compound is triggered after a Quick Fix (single-file, <30 lines):

1. Skip steps 1-5 (full compound is overkill)
2. Ask ONE question: "Would the system catch this automatically next time?"
3. If NO:
   • Add to error-registry if cross-project
   • Add to session-learnings if project-specific
   • Propose a hook or rule if it's a recurring category
4. If YES: log brief entry in session-learnings and move on
5. Update model-performance.json with the model used and outcome