Sw Learn

---
name: sw-learn
description: >-
  Captures patterns and learnings from the current work unit. Reviews
  build failures, gate findings, and architecture decisions. Applies
  objective promotion criteria autonomously — patterns.md is the artifact.
argument-hint: ""
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
---

# Specwright Learn

## Goal

Extract reusable knowledge from the current work unit. Build failures,
gate findings, and architecture decisions contain valuable patterns.
Surface them, let the user curate, and promote the best ones so future
work benefits.

## Inputs

- `{worktreeStateRoot}/session.json` -- selected work for this worktree
- `{repoStateRoot}/work/{selectedWork.id}/workflow.json` -- current work unit (should be shipped)
- `{workDir}/evidence/` -- gate evidence files
- `{workDir}/implementation-rationale.md` -- curated build-time reasoning when present
- `{workDir}/review-packet.md` -- reviewer-facing audit synthesis when present
- `{workDir}/plan.md` -- architecture decisions
- `{workArtifactsRoot}/{selectedWork.id}/approvals.md` -- approval lineage for the work
- `{projectArtifactsRoot}/CONSTITUTION.md` -- existing practices
- `{projectArtifactsRoot}/learnings/` -- prior work unit learnings (for retrospective)
- Git log for the work unit's commits

## Outputs

- Learnings presented to user in categories
- User-approved patterns promoted to one of:
  - `{projectArtifactsRoot}/CONSTITUTION.md` (new practice rule)
  - Auto-memory MEMORY.md (compact pattern entry, loaded every session)
  - `{projectArtifactsRoot}/patterns.md` (reusable pattern library)
- `{projectArtifactsRoot}/learnings/{work-id}.json` -- written when any finding is promoted OR when gateCalibration data is available. When only calibration is present (no promoted findings), write with an empty `findings` array.

## Constraints

**Stage boundary (LOW freedom):**
- Follow `protocols/stage-boundary.md`.
- You capture learnings and promote patterns. You NEVER start new work units, run builds, or create PRs.
- It is not a core workflow stage and never claims top-level work ownership.
- After learnings are captured, STOP and present the handoff:
  - If more work units pending: "Run `/sw-build` to start the next unit."
  - If no more units: "All work units complete. Learnings captured."

**Discovery (HIGH freedom):**
- Scan evidence files, git log, plan.md, `implementation-rationale.md`,
  `review-packet.md`, and approval lineage for patterns worth remembering.
- Look for: what broke, what was hard, what worked well.
- Check as-built notes for discovered behaviors per `protocols/build-quality.md`.
- If `commands.test:integration` is configured in config.json: check gate-build evidence
  for the integration tier. If it was SKIP or absent, surface as a learning candidate
  ("No integration tests ran"). Skip this check when no integration tier is configured.
- MUST record gateCalibration for every gate that ran, even if all PASS with 0 findings. Populate from evidence files automatically. falsePositives array only populated when user explicitly labels a finding as false positive during presentation (dismissal alone does not count). Format per `protocols/evidence.md#verdict-rendering`.

**Curation (MEDIUM freedom):**
- Apply `protocols/decision.md` CURATION criteria autonomously:
  - Candidate for patterns.md: recurs across 2+ units OR known failure category
  - Candidate for TESTING.md: boundary classification or test infra discovery
  - Never auto-promote to constitution or auto-memory (Type 1 — irreversible)
  - Track for later: write a BL-{n} item with `pattern` tag per `protocols/backlog.md`
  - Dismiss: project-specific, non-recurring, low-severity
- Maximum 5-7 learnings. Group by category.
- Auto-promote candidates that meet criteria. Record each promotion decision in
  decisions.md. The human reviews promoted patterns when sw-design loads patterns.md.

**Promotion (LOW freedom):**
- Constitution: add practice with ID (e.g., S6, Q5).
- Auto-memory: write compact entry to MEMORY.md per `protocols/learning-lifecycle.md`.
- Patterns: append to `{projectArtifactsRoot}/patterns.md` (create if missing). Also write a compact one-liner to auto-memory (dual-write rule per protocol).
- Testing strategy: update `{projectArtifactsRoot}/TESTING.md` (if it exists). The `testing` category maps here. Add new boundary classifications, mock allowances, or test infrastructure notes discovered during build. If TESTING.md does not exist, fall back to patterns.md.
- User approves exact wording before saving.

**Retrospective (MEDIUM freedom):**
- When 2+ prior learning files exist, surface recurring patterns across units.

**Persistence (LOW freedom):**
- Write `{projectArtifactsRoot}/learnings/{work-id}.json` when any finding is promoted OR when gateCalibration data is available (mandatory per `protocols/evidence.md#verdict-rendering`). When only calibration is present, write with an empty `findings` array.
- Schema: `{ workId, timestamp, findings: [{ category, source, description, proposedRule, disposition }] }`

**Landscape update (MEDIUM freedom):**
- After persistence, if `{projectArtifactsRoot}/LANDSCAPE.md` exists: identify affected modules from evidence, `implementation-rationale.md`, `review-packet.md`, and plan artifacts, re-scan those modules, merge updates. Show diff, user approves. Update `Snapshot:` timestamp.
- If LANDSCAPE.md doesn't exist: silently skip.

**Audit resolution (MEDIUM freedom):**
- After landscape update, if `{projectArtifactsRoot}/AUDIT.md` exists: check if work unit's changed files overlap with open finding locations. If finding is addressed, move to `## Resolved` with work unit ID. User approves.
- If AUDIT.md doesn't exist: silently skip.

**Enrichment (MEDIUM freedom):**
- Optional per `protocols/insights.md`. Silently skip if unavailable or stale.

**Auto-memory (MEDIUM freedom):**
- Per `protocols/learning-lifecycle.md`. If auto-memory directory doesn't exist or system prompt doesn't mention auto-memory, silently fall back to patterns.md only.

**State cleanup (LOW freedom):**
- Resolve the selected work from the current worktree session. If another live
  top-level worktree owns it, STOP with explicit adopt/takeover guidance.
- Before clearing, verify the selected work's status is `shipped`. If it is
  anything else (e.g. `building`, `verifying`), STOP with:
  "State cleanup requires status 'shipped'. Current status: {status}. Complete the current build cycle before running /sw-learn."
- After ALL persistence steps complete successfully (learnings JSON write,
  LANDSCAPE.md update, AUDIT.md resolution), clear the current worktree session
  attachment:
  - Acquire the selected work lock per `protocols/state.md` before other mutations.
  - Follow `protocols/state.md` read-modify-write sequence.
  - Set `{worktreeStateRoot}/session.json.attachedWorkId` to `null`.
  - Clear the selected work's attachment record and release the lock.
  - Preserve the selected work record, `workUnits`, `gates`, and shipped
    history for future retrospectives.
- If ANY persistence step fails (learnings write, landscape update, audit resolution): STOP with error. Do NOT clear the current worktree session attachment. The user must fix the failure and re-run `/sw-learn`.
- This is the `shipped → (none)` transition defined in `protocols/state.md`.

## Protocol References

- `protocols/stage-boundary.md` -- scope, termination, and handoff
- `protocols/decision.md` -- autonomous decision framework (CURATION heuristics)
- `protocols/context.md` -- anchor doc loading
- `protocols/state.md` -- workflow state reading and cleanup transition
- `protocols/insights.md` -- session pattern enrichment
- `protocols/learning-lifecycle.md` -- promotion targets and auto-memory format
- `protocols/landscape.md` -- codebase reference document format
- `protocols/audit.md` -- codebase health findings format
- `protocols/backlog.md` -- backlog item format and write targets
- `protocols/build-quality.md` -- as-built notes and discovered behaviors
- `protocols/approvals.md` -- approval lineage consumption
- `protocols/review-packet.md` -- reviewer packet consumption
- `protocols/evidence.md#verdict-rendering` -- gate calibration data recording

## Failure Modes

| Condition | Action |
|-----------|--------|
| No completed work unit | "Nothing to learn from. Complete a build cycle first." |
| No evidence files | Skip evidence scanning, focus on git log and plan |
| User dismisses all learnings | Calibration data still written (mandatory). Findings array empty. |
| Insights unavailable/stale | Silently skip enrichment per `protocols/insights.md` |
| Auto-memory unavailable | Silently fall back to patterns.md only |