Learning Loop

learning-loop Skill v4.2

> Version history: references/CHANGELOG.md (v4.2 = progressive-disclosure restructure, no behavior change; v4.1 = W7.w Step-3/3a Sub-Agent STOP gates; v4.0 = Mods 6-10 hygiene pass + Phase 2 gatekeeper retired). > > Sub-agent prompt library: the six dispatch prompts live in references/prompts/ and are read AT DISPATCH TIME — see "Sub-Agent Prompt Library" section below. STOP if a prompt file is missing: never improvise a replacement prompt from memory — surface the missing file to the user instead.

Purpose: Two-mode learning capture — raw signal scanning mid-session, quality-gated consolidation at session end. Handles process-level and content-level capture; code-level capture is the user's responsibility via direct /ce-compound invocation mid-session (peak-fresh context).

---

Mode Detection

When /learning-loop is invoked, determine which mode to run:

| User says | Mode | Why | |---|---|---| | /learning-loop + "before I clear" / "context long" / "mid-session" | Scan | Context clues indicate mid-session | | /learning-loop + "wrap up" / "done" / "end session" / "consolidate" | Wrap-up | Context clues indicate session end | | /learning-loop scan | Scan | Explicit override | | /learning-loop wrap up | Wrap-up | Explicit override | | /learning-loop (no context clues) | Ask | "Mid-session scan or session-end wrap-up?" |

Wrap-up scope: Wrap-up always consolidates the current session's captures. If other session directories exist, they are surfaced for triage (see Wrap-up Step 2) — the user decides whether to include, skip, or delete them.

Detection logic:

1. Check if the user passed an explicit argument (scan or wrap up)
2. If no argument, scan the user's recent messages for context clues:

• Scan clues: "before I clear", "context getting long", "going to compact", "mid-session", "save progress"
• Wrap-up clues: "wrap up", "done for now", "end session", "ending", "consolidate", "finally done"

1. If ambiguous or no clues, ask: "Mid-session scan (preserves raw signals) or session-end wrap-up (consolidates everything)?"

---

⚠️ MANDATORY PROCEDURES

Sub-Agent Rule

When running Scan mode:

1. DO NOT do capture work in main conversation — this wastes context
2. SPAWN a Task agent using the SCANNER_PROMPT
3. Sub-agent writes to ~/.claude/learning-captures/[session-id]/scan-NNN.md
4. Main conversation waits for completion, then confirms capture is done

STOP: If you're about to scan for signals yourself in the main conversation, you're doing it wrong. Spawn a sub-agent.

User Verification (Critical)

Before routing ANY learning to a destination:

1. Present a summary of captured/consolidated signals to the user
2. Explicitly ask for verification — "Does this accurately reflect what happened?"
3. Wait for user confirmation before routing to CLAUDE.md, Judgment Ledger, or Memory

> Why this exists (Jan 29, 2026): AI-generated captures can contain hallucinations — wrong names, fabricated premises, misremembered details. A capture once got the user's husband's name wrong and claimed constraints that didn't exist.

DO NOT update any destination based on captures without user sign-off.

Skill Version Ship Verification (added v3.6 Apr 28 2026)

When shipping a new version of this skill (or any skill that adds bootstrap state files, accumulator logs, or one-time initialization):

1. Enumerate every bootstrap step the new version added — accumulator file creation, sentinel file writes, decision-log initialization, schema migrations, etc.
2. Run them, OR confirm they will be triggered by a downstream workflow step that has actually fired.
3. Verify each artifact exists on disk before declaring the version "shipped."

STOP and correct if you're:

• About to declare a new skill version "shipped" / "live" / "deployed" without checking that the version's added bootstrap files exist
• Assuming "Step N will create the file when it first runs" without confirming Step N has run at least once after the ship

> Why (Apr 28, 2026): v3.5 Phase 1 Persona Panel shipped with three new files supposed to be bootstrapped by Step 4c (persona-eval-runs.txt, phase-1-ship-date.txt, eventually phase-1-decision-log.md). At ship time none existed, because Step 4c only runs DURING a wrap-up — and no wrap-up had run yet under v3.5. Step 1b.5 read these files at the next wrap-up start, found them missing, and silently took the "skip Phase 1 evaluation entirely" branch. The Phase 1 self-evaluation gate would have stayed dormant indefinitely. Caught only by explicit consolidation analysis. Section 1d Verification rule in root CLAUDE.md covered this trigger semantically ("infrastructure done after writing files but before running them") but didn't fire on this ship — this STOP is the enforcement upgrade.

---

Core Insight

> "The human shouldn't need to remember."

Context compaction and /clear destroy details. Files persist. This skill ensures:

1. Learnings are captured before compaction erases them
2. The right tool is named for the right capture type — process/content capture happens in wrap-up; code-level capture is user-invoked /ce-compound mid-session (this skill does NOT orchestrate /ce-compound)
3. Nothing falls through the cracks — even when you forget to document

---

Why Explicit Invocation

v2 relied on a triggers YAML field, but triggers is not a supported field in Claude Code's SKILL.md spec. The only auto-invocation mechanism is description-based matching — Claude's LLM matches user requests to the skill's description field. This is non-deterministic: distinctive phrases like "run a capture" matched often enough to produce capture files, while common phrases like "wrap up" were too generic and consistently failed to invoke the skill — handled conversationally or intercepted by auto-memory instead.

Result: Scan-like invocations worked intermittently, but wrap-up never triggered reliably. Capture files accumulated across sessions with no consolidation phase to process them.

v3 fix: Explicit /learning-loop invocation is deterministic. Both modes fire exactly when intended — no reliance on LLM matching heuristics.

Auto-Memory Coexistence

Claude Code also has a built-in auto-memory feature that intercepts natural-language phrases like "capture" and "remember this." Explicit invocation avoids this secondary concern too:

| Feature | Auto-Memory | Learning-Loop | |---------|-------------|---------------| | Invocation | Natural language ("remember this", "capture") | Explicit /learning-loop command | | Scope | Quick facts, preferences | Multi-signal session analysis with quality gates | | Output | MEMORY.md entries | Routed to 6 destinations based on type (or Noted/dropped) | | Quality gates | None (direct write) | Type-specific gates + user verification |

Complementary, not competing:

• Auto-memory handles quick "remember X" requests — let it
• Learning-loop handles structured session analysis — explicit invocation ensures it runs when intended
• Memory (MEMORY.md) is one of learning-loop's routing destinations, but learning-loop applies quality gates first

---

Operation 1: Scan Mode

User story: "I'm mid-task, context is getting long, but I'm not done yet."

What Scan Does

• Spawn sub-agent → scan conversation for raw signals (unresolved observations, not conclusions)
• Write to ~/.claude/learning-captures/[session-id]/scan-NNN.md
• No routing, no conclusions, no quality gates on the signals themselves. Back to work.

Scan Process

1. Determine session-id (date + brief context, e.g., 2026-02-24-learning-loop-v3)

1. Create session directory:

``bash mkdir -p ~/.claude/learning-captures/[session-id] ``

1. Determine scan number:

``bash ls ~/.claude/learning-captures/[session-id]/scan-*.md 2>/dev/null | wc -l `` Next scan = count + 1, zero-padded (scan-001.md, scan-002.md, etc.)

1. Spawn scanning sub-agent with SCANNER_PROMPT (Read references/prompts/scanner-prompt.md at dispatch)

1. After capture completes, confirm:

`` "Scan complete — captured [N] raw signals to scan-[NNN].md. These are unresolved observations, not conclusions. Safe to continue or compact. I'll consolidate everything at wrap-up." ``

SCANNER_PROMPT (Raw Signal Mode)

Read references/prompts/scanner-prompt.md at dispatch time and use its content (below the header) as the sub-agent prompt, substituting [session-id] and [NNN]. Verbatim v4.1 content — includes the mandatory Recurrence Test (v3.9), the seven signal types, scratch-file cross-referencing, and the scan output schema. STOP if the file is missing — surface to user; do not improvise a scanner prompt.

---

Operation 2: Wrap-up Mode

User story: "I'm finally done — maybe sessions later. Make sense of everything."

What Wrap-up Does

1. Scan current session — this context hasn't been captured yet
2. Triage captures — show this session's captures + surface any orphaned sessions for user decision
3. Resolve with hindsight — which hypotheses were right? What actually worked?
4. Apply quality gates on conclusions (not raw signals)
5. User verification — present summary, wait for confirmation
6. Route to destinations based on type
7. Clean up capture files

Wrap-up Process

Step 1: Scan Current Session

Run a scan of the current session first (same as Scan mode), since this context hasn't been captured yet. This ensures the final session's signals are included.

Step 1b: Deferred Methodology Check (MANDATORY)

Before consolidating, scan for failures in this session that match the revisit_triggers of any deferred methodology memory. This binds deferred-methodology review to the session-end event so deferred investigations accumulate real production evidence instead of rotting.

STOP before proceeding to Step 2 unless all of the following have been produced:

1. Enumerate deferred methodologies. Evidence: paste the output of

``bash for f in ~/.claude/projects/*/memory/*.md; do [ "$(basename "$f")" = "MEMORY.md" ] && continue if grep -q "^status:[[:space:]]*deferred[[:space:]]*$" "$f" 2>/dev/null; then echo "$f" fi done ``

If no deferred methodologies exist, state "No deferred methodologies found" and skip to Step 2.

1. Scan the session for failure events. Review the session transcript for:

• User pushback calling out premature completion ("said done but wasn't", "skipped a step", etc.)
• Stop hook catches ({"ok": false, "reason": "..."} messages)
• Your own acknowledged mistakes that fit a deferred methodology's failure mode

1. Cross-reference. For each deferred methodology, check its revisit_triggers (regex, case-insensitive) against the session's failure events. Evidence: paste each memory's triggers list and the matched session evidence.

1. If any match, surface to the user in this shape:

``` ⚠️ Deferred methodology resurfaced: [name from memory]

• Matched trigger: [regex pattern]
• Session failure evidence: [specific quote/line from transcript]
• This methodology was deferred pending production data; the session provided fresh evidence.
• Decision: (a) implement now this session, (b) next session, (c) keep deferred + append incident

```

1. If user chooses "keep deferred + append incident" OR "next session", append a dated entry to the memory file's ## Incidents section:

```markdown ### [YYYY-MM-DD] [session-id-short] — [skill involved, if identifiable]

• Failure: [quote or paraphrase]
• Gate form at failure: [compact-imperative / descriptive-label / none / N/A]
• Would the deferred methodology have prevented it? [yes / no / unclear — with reasoning]

```

1. If user chooses "implement now", scope it as part of this wrap-up OR spin out an immediate task.

1. If no matches, say so in one line and proceed to Step 2. No noise when nothing matches.

Complement: the ~/.claude/hooks/deferred-methodology-detector.py UserPromptSubmit hook fires the same check in-session when failure phrases are typed in real time. This step is the session-end retrospective backstop for cases the in-session hook missed or where the user wants a consolidated review.

> Why this step exists (Apr 22, 2026): Memory entries that say "revisit later" rot without an active trigger. The gate-template production test memory was the motivating case — deferred pending production data, but prior to this wiring had no mechanism to resurface automatically. Generalized to any status: deferred memory so future deferrals inherit the behavior.

Step 1b.5: Phase 1 Persona Panel Evaluation Check (added v3.5 Apr 28 2026)

Active when Phase 1 shadow mode is in flight. Skip entirely if ~/.claude/learning-captures/persona-eval-runs.txt does not exist (Phase 1 not yet shipped or already past Phase 1).

If the file exists:

1. Read accumulators:

• Count entries (excluding the header line) in persona-eval-runs.txt
• Read first-entry timestamp from same file
• Read ~/.claude/learning-captures/phase-1-ship-date.txt for Phase 1 ship date (set in Step 4c bootstrap)
• Read ~/.claude/learning-captures/phase-1-decision-log.md if it exists — most recent decision marks where Phase 1 stands today

1. Trigger condition (per D2): evaluation fires if BOTH:

• count ≥ 3 (≥3 prior shadow runs accumulated, not counting this current wrap-up) OR (today - phase_1_ship_date) ≥ 7 days, whichever first
• AND the latest entry in phase-1-decision-log.md is NOT a recent decision ( — Decision:

Eval window: to ( runs) Metrics: match=, coverage=, noise= Sub-agent recommendation: User decision: Reasoning: ```

d. Per D2: the decision applies to the NEXT wrap-up's Step 3a behavior, not this current wrap-up. This wrap-up proceeds as scheduled (consolidation + Step 3a personas in shadow mode + Step 4).

1. If trigger condition not met but Phase 1 is active: append a one-line note to the user — Phase 1 still accumulating data: of 3 runs, days since ship. Proceed to Step 2.

1. If persona-eval-runs.txt does not exist: Phase 1 not yet shipped (or already past Phase 1 — gatekeeper or revert). Skip this sub-step entirely.

> Why this step exists (Apr 28, 2026): The persona panel needs a self-evaluating decision gate at 4 wrap-ups or 7 days post-ship. Without binding the eval trigger to a workflow step that fires every wrap-up, the eval would rot the same way deferred methodology memories do. Step 1b.5 binds the eval to /learning-loop wrap-up itself — the same enforcement principle that worked for Step 1b.

Step 2: Triage Captures

ls -la ~/.claude/learning-captures/*/scan-*.md ~/.claude/learning-captures/*/scratch.md 2>/dev/null

List all capture files with timestamps, then present a triage view.

Archive-dir convention (added May 18, 2026): Directories under ~/.claude/learning-captures/ whose names start with _ (e.g., _archive/) are archive locations for preserved reference fixtures, NOT active sessions. They MUST be excluded from the "Other Sessions Found" listing — they will not contain scan-*.md or scratch.md files, but a careless ls -la of the parent dir will surface them as "unknown session dirs" and trigger recurring "what is this?" confusion at every wrap-up. When constructing the triage view, filter out any directory whose basename starts with _. The glob above naturally skips them (no matching scan/scratch files inside) — preserve this property; do not switch to a broader directory listing without the _* prefix filter. Why this exists: cited fi

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: melodykoh
• Source: melodykoh/learning-loop-skill
• License: MIT

Install and usage instructions live in the source repository linked above.