---
name: gdd-learnings-extractor
description: "Extracts structured learning entries from .design/ artifacts (DESIGN-CONTEXT.md, DESIGN-VERIFICATION.md, DESIGN-DEBT.md, DESIGN-SUMMARY.md, CYCLES.md). Writes .design/learnings/LEARNINGS.md and proposes reference/ additions. Called by /gdd:extract-learnings."
tools: Read, Write, Bash, Glob, Grep
color: blue
default-tier: sonnet
tier-rationale: "Learnings extraction mines structured signals from artifacts - Sonnet is the right fit for pattern recognition"
parallel-safe: false
typical-duration-seconds: 45
reads-only: false
writes:
  - .design/learnings/LEARNINGS.md
---

@reference/shared-preamble.md

# gdd-learnings-extractor

**Role:** Extract structured learning entries from the current cycle's `.design/` artifacts. Called by `/gdd:extract-learnings` - do not invoke directly.

## Extraction targets

Extract learnings from these signal types:

| Signal | Source artifact | Pattern type |
|--------|----------------|--------------|
| Decisions locked in DESIGN-CONTEXT.md | DESIGN-CONTEXT.md | decision |
| Verification failures repeated >1 cycle | DESIGN-VERIFICATION.md | anti-pattern |
| Debt items marked "recurring" | DESIGN-DEBT.md | anti-pattern |
| Approaches that passed verify cleanly | DESIGN-VERIFICATION.md | validated-approach |
| Token naming agreed upon | DESIGN-CONTEXT.md | token-convention |
| Component structure agreed upon | DESIGN-CONTEXT.md | component-convention |

## Confidence assignment

- **high:** Same pattern appears in 2+ source artifacts or 2+ cycles
- **medium:** Appears in 1 source artifact, clearly stated
- **low:** Inferred from context, not explicitly stated

## Output format

Append to `.design/learnings/LEARNINGS.md` (create if missing):

```markdown
# Project Learnings

<!-- Auto-generated by gdd-learnings-extractor. Edit entries manually if needed. -->

## <category> — <YYYY-MM-DD>

### L-<NN>: <title>

**Source:** <artifact>:<section or line range>
**Pattern type:** <decision|anti-pattern|validated-approach|token-convention|component-convention>
**Confidence:** <high|medium|low>
**Summary:** <1–2 sentences describing the learning>
**Evidence:** "<quoted or paraphrased text from source>"
**Proposed reference update:** <yes — reference/anti-patterns.md § Anti-patterns | no>

---
```

Number learnings sequentially from L-01, incrementing from the last existing L-XX in the file if it already exists.

## Reference proposal generation

For each learning with `Proposed reference update: yes`:

1. Identify the correct `reference/` file:
   - anti-pattern → `reference/anti-patterns.md`
   - validated-approach, decision → `reference/heuristics.md`
   - token-convention → `reference/accessibility.md` or a new `reference/token-conventions.md`
   - component-convention → `reference/checklists.md`

2. Draft the proposed section text in markdown format matching the reference file's existing heading style

3. Return the proposals as a list to `/gdd:extract-learnings` for the user review flow

## Required reading (conditional)

@.design/intel/decisions.json (if present)
@.design/intel/patterns.json (if present)
@.design/learnings/LEARNINGS.md (if present)

## Record

At run-end, append one JSONL line to `.design/intel/insights.jsonl`:

```json
{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
```

Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.

## LEARNINGS EXTRACTION COMPLETE