phase-learning-extraction

source	shipped
name	phase-learning-extraction
description	Use when completed work should produce reusable decisions, lessons, surprises, and patterns for future phases
type	colony
domains	["knowledge-management","retrospective","continuous-improvement"]
agent_roles	["keeper","chronicler"]
workflow_triggers	["continue","seal"]
task_keywords	["learning","lessons","retrospective","pattern","decision"]
priority	normal
version	1.0

Phase Learning Extraction

Purpose

Extract structured decisions, lessons, patterns, and surprises from completed phase artifacts. Produces a LEARNINGS.md file that feeds the colony's knowledge base for future phases and milestones.

When to Use

• A phase completes (aether continue runs successfully)
• A milestone finishes and you want to capture cross-phase insights
• User asks "what did we learn?", "capture learnings", or "retrospective"
• Before archiving a milestone to ensure knowledge is preserved
• When starting a new phase and wanting to review relevant past learnings

Instructions

Extract from Phase

1. Read phase artifacts in order:

   • .aether/phases/{N}/PLAN.md -- original plan and intent
   • .aether/phases/{N}/IMPLEMENTATION.md -- what was actually built
   • .aether/phases/{N}/TEST_RESULTS.md -- test outcomes (if exists)
   • .aether/phases/{N}/REVIEW.md -- code review findings (if exists)
   • .aether/data/phase-manifest.json -- commit references and timing

2. Extract four categories:

   Decisions -- Explicit choices made during implementation

   • Format: {decision} | {rationale} | {alternatives considered}
   • Source: IMPLEMENTATION.md decision blocks, commit messages, conversation

   Lessons -- Things that went wrong or could be improved

   • Format: {lesson} | {context} | {action for next time}
   • Source: Test failures, review findings, late-stage changes

   Patterns -- Reusable approaches that worked well

   • Format: {pattern} | {where used} | {when to reuse}
   • Source: Code structure, test approaches, workflow steps

   Surprises -- Unexpected outcomes, good or bad

   • Format: {surprise} | {impact} | {mitigation if negative}
   • Source: Performance results, integration issues, scope changes

3. Write .aether/phases/{N}/LEARNINGS.md:

   # Learnings -- Phase {N}: {name}
   
   ## Decisions ({count})
   | Decision | Rationale | Alternatives |
   |----------|-----------|--------------|
   | {decision} | {why} | {what else was considered} |
   
   ## Lessons ({count})
   | Lesson | Context | Next Time |
   |--------|---------|-----------|
   | {lesson} | {situation} | {improvement} |
   
   ## Patterns ({count})
   | Pattern | Used In | Reuse When |
   |---------|---------|------------|
   | {pattern} | {files/areas} | {conditions} |
   
   ## Surprises ({count})
   | Surprise | Impact | Resolution |
   |----------|--------|------------|
   | {surprise} | {effect} | {how handled} |
   

4. Append summary entries to .aether/data/colony-knowledge.jsonl for cross-phase querying

Extract from Milestone

1. Collect all phase LEARNINGS.md files within the milestone
2. Cross-reference to find recurring patterns, repeated lessons, and milestone-wide decisions
3. Produce .aether/milestones/{N}/LEARNINGS.md with aggregated insights plus a "Milestone Themes" section highlighting the top 3-5 cross-cutting themes

Key Patterns

• Specific over vague: "Use connection pooling for database queries under load" beats "Database was slow"
• Actionable: Every lesson must include what to do differently next time
• Taggable: Each entry gets tags from the colony taxonomy (performance, security, ux, architecture, testing, devops)
• Deduplication: When extracting from milestone, merge similar entries across phases rather than listing each occurrence

Output Format

Extracted learnings from Phase 3 (Dashboard UI):
  7 decisions | 3 lessons | 4 patterns | 2 surprises
  Written to .aether/phases/3/LEARNINGS.md
  Colony knowledge base updated (47 total entries)

Examples

# Extract from completed phase
> learning-extractor --phase 3

# Extract from entire milestone
> learning-extractor --milestone 1

# Review specific category
> learning-extractor --phase 5 --category lessons