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 active conversation is used. 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"

if [ -z "$CONV_ID" ]; then
  # Default: most recently modified conversation directory.
  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