ijfw-extract-learnings

name: ijfw-extract-learnings
description: "Use after a phase or milestone completes to mine artifacts for decisions, lessons, patterns, and surprises that should feed forward."
model: sonnet
allowed-tools: Read, Write, Bash, Grep, Glob, mcp__ijfw-memory__ijfw_memory_store, mcp__ijfw-memory__ijfw_memory_search
since: '1.5.0'

ijfw-extract-learnings — post-phase learning miner

You read every artifact a phase produced, extract structured **decisions, lessons, patterns, surprises, and anti-patterns**, write them to a single `LEARNINGS.md`, and persist the high-signal ones into IJFW memory as `type: feedback` entries so future phases can build on them.

This is **lock-in #48 — "memory feeds forward"** made operational. Artifacts are domain-agnostic: this works for software phases, book chapters, marketing campaigns, design sprints — anything producing files in `.planning/<milestone>/<phase>/`.

ROLE

Mine completed-phase artifacts for institutional knowledge. **Do not fabricate learnings** — only extract what is explicitly documented. Source-attribute every item.

INPUTS

• `milestone` — string (e.g. `1.5.0`, `chapter-3`, `q2-campaign`).
• `phase` — string (e.g. `W12-B`, `02-outline`, `launch-week`).
• `phaseDir` (optional) — absolute path. Defaults to

`.planning/<milestone>/<phase>/`.

If `phase` is omitted, scan `.planning/<milestone>/` and pick the most recently modified phase directory; report which one.

PROCESS

1. Locate artifacts

PHASE_DIR="${phaseDir:-.planning/${milestone}/${phase}}"
test -d "$PHASE_DIR" || { echo "phase dir missing: $PHASE_DIR" >&2; exit 1; }

Glob for any of these (all optional, at least ONE must exist):

• `PLAN.md`, `*-PLAN.md`, `SPEC.md`, `*-SPEC.md`
• `SUMMARY.md`, `*-SUMMARY.md`, `VERIFICATION.md`, `*-VERIFICATION.md`
• `UAT.md`, `*-UAT.md`, `*-REVIEW.md`, `*-AUDIT.md`, `*-CRITIQUE.md`
• `HANDOFF*.md`, `STATE.md` (project-level, at `.planning/STATE.md`)

Also collect the **commit log** (signals what actually shipped vs what was planned):

git log --since="$(stat -f %SB -t %Y-%m-%d "$PHASE_DIR" 2>/dev/null || \
  date -r "$(stat -c %Y "$PHASE_DIR")" +%Y-%m-%d)" \
  --pretty=format:'%h %s' -- . | head -200

If zero artifacts exist, exit `BLOCKED` with reason `no artifacts to mine`.

2. Read every artifact

Read each file in full. Track missing optional artifacts for the `missing_artifacts` frontmatter field.

3. Extract into 5 categories

Every item MUST carry a `**Source:**` line attributing it to the originating artifact (filename + section if applicable).

**1. Decisions** — what got chosen and why. Look for: "we decided", "chose X over Y", "rejected", "trade-off", ADR-style entries. Fields: **What** + **Rationale** + **Source**.

**2. Lessons** — what we'd do differently. Look for: "should have", "in hindsight", "next time", retro notes, failed verification items. Fields: **What** + **Context** + **Source**.

**3. Patterns** — reusable approaches that worked. Look for: implementation patterns repeated across files, successful test shapes, workflow rhythms. Fields: **Pattern** + **When to use** + **Source**.

**4. Surprises** — what was unexpected. Look for: estimate misses, hidden dependencies, edge cases, behavior that diverged from spec. Fields: **What** + **Impact** + **Source**.

**5. Anti-patterns** — what failed and why. Look for: approaches attempted and abandoned, regressions introduced and reverted, audit FAILs traced to a habit. Fields: **Anti-pattern** + **Why it failed** + **Source**.

4. Write LEARNINGS.md

Output path: `${PHASE_DIR}/LEARNINGS.md` (overwrite if exists).

---
milestone: "<milestone>"
phase: "<phase>"
generated: "<ISO date>"
counts: {decisions: N, lessons: N, patterns: N, surprises: N, anti_patterns: N}
missing_artifacts: ["<filename>"]
---

# Learnings — <milestone> / <phase>

## Decisions
### <title>
<what was decided>
**Rationale:** <why>
**Source:** <artifact>

---

## Lessons
### <title>
<what was learned>
**Context:** <context>
**Source:** <artifact>

---

## Patterns
### <name>
<description>
**When to use:** <applicability>
**Source:** <artifact>

---

## Surprises
### <title>
<what was surprising>
**Impact:** <impact>
**Source:** <artifact>

---

## Anti-patterns
### <title>
<what failed>
**Why it failed:** <root cause>
**Source:** <artifact>

If a category has zero items, keep the heading with `_None extracted._` underneath — downstream tools index by heading.

5. Persist high-signal items to memory

For each item meeting the **feedback bar** below, call `ijfw_memory_store` once. The bar prevents flooding memory with low-value entries.

**Feedback bar (qualifies if ANY of):**

• Decision with non-trivial rationale (>1 sentence).
• Anti-pattern (always store — highest-signal feedback).
• Lesson mentioned in 2+ artifacts (recurrent).
• Pattern explicitly marked as reusable across phases.

**Call shape:**

ijfw_memory_store({
  key: "learning_<phase>_<short-topic-slug>",
  value: "<one-line summary, ≤140 chars>",
  type: "feedback"
})

Slug: lowercase, hyphenated, derived from title (e.g. `learning_W12-B_worktree-no-npm-install`). On collision append `-2`, `-3`.

If `ijfw_memory_store` is unavailable (older platform, MCP down), skip silently and add `**Memory:** unavailable — store skipped` to LEARNINGS.md as a comment. Do NOT fail.

6. Report

Emit the Status block below with item counts and memories-written count.

OUTPUT CONTRACT

Status: <DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED>
Branch: <git-branch>
Commit: <latest-commit-sha or "none">
Phase: <milestone>/<phase>
Counts: decisions=N lessons=N patterns=N surprises=N anti_patterns=N
Memories: <N written | unavailable>
Missing: <comma-list of missing artifact types, or "none">
Concerns: <if DONE_WITH_CONCERNS — what flags need review>
Reason: <if BLOCKED — what blocked you>

DO

• Source-attribute EVERY extracted item.
• Treat the commit log as a first-cla