/learn

/learn Command

Distill a finished conversation into classified knowledge candidates and propose (never auto-apply) memory writes or a new-skill hand-off. Closes the loop between a completed agent chain and the persistent memory system.

Usage

/learn [conversation_id]

`conversation_id` is optional — when omitted, the session's own conversation_id (from the task/session context) is used; only if none is known does it fall back to the most recently modified directory (conversations are shared across machines, so the newest mtime may belong to another machine's session). It MUST be a UUID (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`).

What It Does

1. Resolves the `conversation_id` 2. Locates `context.md`, the design `## Decisions` section, and drains any low-confidence candidates queued in `.scaffolding/.ingest-queue` 3. Exits cleanly if there is nothing to distill 4. Distills the conversation into knowledge candidates 5. Classifies each candidate: memory entry vs new-skill proposal 6. Dry-run proposes the changes; applies only on explicit confirmation

Apply the `distill` skill (Conversation-Scoped Distillation + Skill Promotion Criterion) and the `agent-memory` skill (Learning Loop) throughout.

Steps

Follow these steps exactly.

1. Resolve the conversation_id

CONV_ID="$1"

# Prefer the session's conversation_id (from the task/session context) when the
# caller passed none. SESSION_CONV_ID stands for that value; leave it empty if unknown.
[ -z "$CONV_ID" ] && CONV_ID="${SESSION_CONV_ID:-}"

if [ -z "$CONV_ID" ]; then
  # Fallback only: most recently modified conversation directory. The trailing
  # slash makes the glob follow the conversations symlink.
  CONV_ID=$(ls -1dt .scaffolding/conversations/*/ 2>/dev/null | head -1 | xargs -r basename)
fi

UUID_RE='^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$'
if ! echo "$CONV_ID" | grep -qE "$UUID_RE"; then
  echo "ABORT: '$CONV_ID' is not a valid conversation UUID."
  exit 1
fi

echo "Conversation: $CONV_ID"

2. Locate the input files

CONV_DIR=".scaffolding/conversations/$CONV_ID"
CONTEXT_FILE="$CONV_DIR/agent-memory/context.md"
DESIGN_FILE="$CONV_DIR/specs/design.md"

if [ ! -f "$CONTEXT_FILE" ]; then
  echo "Nothing to distill: $CONTEXT_FILE does not exist."
  echo "The /learn command exits cleanly — no conversation memory to process."
  exit 0
fi

echo "Found context: $CONTEXT_FILE"
if [ -f "$DESIGN_FILE" ]; then
  echo "Found design:  $DESIGN_FILE"
else
  echo "No design.md — distilling from context.md only."
fi

# Drain low-confidence candidates queued by the memory-ingest Stop hook.
INGEST_QUEUE=".scaffolding/.ingest-queue"
if [ -s "$INGEST_QUEUE" ]; then
  echo "Found ingest queue: $INGEST_QUEUE ($(wc -l < "$INGEST_QUEUE") lines)"
fi

The absence of `context.md` is the explicit "nothing to distill" clean-exit branch — it is a success, not an error.

`.scaffolding/.ingest-queue` is an additional, optional source of **low-confidence (< 0.8) candidates** dropped by the auto-ingest Stop hook (JSONL breadcrumbs + candidates). Treat each queued entry as a candidate for the same propose-then-confirm flow below. After a candidate is applied (or the user declines it), drop its line so the queue does not re-propose it.

3. Distill the conversation

Read `context.md` and, if present, the `## Decisions` section of `design.md`. Apply the `distill` skill's **Conversation-Scoped Distillation** mode:

• Use the Knowledge Candidate Criteria — for a single conversation, rely on the

Decision-section and pattern-keyword criteria (the cross-conversation criterion does not apply).

• Score each candidate with the Confidence Scoring table.

If no candidate clears the bar, report "nothing to distill" and exit cleanly.

4. Classify each candidate

For every candidate, apply `distill`'s **Skill Promotion Criterion**:

• **Memory entry** — a situational insight, gotcha, or one-off decision. Route to

a tier per the `agent-memory` Learning Loop: `shared`, `agent:{name}`, or the conversation tier.

• **New skill** — a repeatable procedure or methodology. Do not write memory;

instead draft a `/create-skill` proposal.

5. Dry-run propose

By default `/learn` writes nothing. Print:

• For each memory candidate: the target file, the proposed appended bullet(s),

and the resulting line count (flag if `KNOWLEDGE.md` would exceed 200 lines).

• For each skill candidate: a pre-filled `/create-skill` draft (name, purpose,

2–4 triggers, SKIP neighbours).

Then ask the user to confirm before applying anything.

6. Apply on confirmation

Only after explicit confirmation:

echo "Applying confirmed candidates..."

• Append memory entries to their target files. If a `KNOWLEDGE.md` write would

exceed 200 lines, overflow lower-confidence entries to the most relevant agent `MEMORY.md` per the `distill` overflow rule.

• Keep each individual file edit under 200 lines — split larger writes.
• For skill candidates, instruct the user to run the proposed `/create-skill`

invocation; `/learn` does not create skills itself.

7. Report

Print a summary: candidates found, memory entries applied (per tier), and skill proposals handed off. Note that applied memory becomes auto-injected context on the next task.

Notes

• `/learn` is propose-then-confirm — it never silently pollutes auto-injected

`KNOWLEDGE.md`.

• It is backend-free: it reads only `.scaffolding/conversations/{id}/` markdown,

with no session-log mining and no database.

• Running `/learn` on a conversation with no `context.md` is safe and exits 0.