/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