/learn — Knowledge Compiler

Orientation

Use when: You have a completed campaign or evolve cycle and want to compile its findings into the project's growing knowledge wiki — so future sessions start smarter, not from scratch.

Don't use when: You want a structured incident analysis first (use /postmortem — run it before /learn); you haven't finished any campaigns (nothing to compile); you want a context transfer only (use /session-handoff).

Key difference from appending: /learn doesn't create isolated per-campaign files. It integrates new findings into existing wiki pages — updating evidence lists, raising confidence where a pattern is confirmed again, and flagging contradictions. A wiki is a compiler; a log is an interpreter.

Invocation Forms

/learn                              — most recently completed campaign
/learn {slug}                       — specific campaign by slug
/learn {file-path}                  — specific campaign file path
/learn --from-evolve {target}       — compile from /evolve pattern library
/learn --from-evolve {target} --cycle {n}  — specific evolve cycle only
/learn --lint                       — lint-only pass (no new extraction)
/learn --compile                    — re-compile staging area into wiki (no new extraction)
/learn --memory                     — compile semantic memory blocks from planning artifacts
/learn --doc-sync                   — process doc-sync queue into .planning/doc-sync/latest.md

Inputs

1. A campaign slug, file path, evolve target, or "most recent" resolution
2. Corresponding postmortem in .planning/postmortems/ (optional)
3. .planning/telemetry/audit.jsonl filtered to this campaign (optional)
4. For --from-evolve: .planning/evolve/{target}/pattern-library.md

Protocol

Step 1: RESOLVE TARGET

If /learn (no argument):

• Glob .planning/campaigns/completed/*.md or .planning/campaigns/*.md where Status: completed
• Sort by modification time descending, take most recent
• If none found: "No completed campaigns found. Run /learn after a campaign completes." Stop.

If /learn {slug}:

• Search .planning/campaigns/ for a file whose name contains {slug}
• Check .planning/campaigns/completed/ if not found in active
• If still not found: "No campaign found matching '{slug}'."

If /learn --from-evolve {target}:

• Read .planning/evolve/{target}/pattern-library.md — this is the source
• If --cycle {n}: filter to sections beginning with ## Cycle {n} only
• If file not found: "No evolve pattern library for '{target}'." Stop.

If /learn --doc-sync: Run:

node hooks_src/doc-sync.js

Then review .planning/doc-sync/latest.md. Stop after reporting the queue count, files surfaced, skipped deleted files, and report path. Do not run campaign extraction unless the user separately asks for it.

If /learn --lint, /learn --compile, or /learn --memory: Skip to Step 4, 5, or 5.5 respectively.

Step 2: GATHER SOURCES

For campaign-based runs only (skip for --from-evolve):

Campaign file (required):

• Full content — direction, phases, Decision Log, circuit breaker activations

Postmortem (optional):

• Search .planning/postmortems/ for files matching *{slug}*
• If not found: note "Postmortem not found — proceeding without it" and continue

Audit telemetry (optional):

• Read last 200 lines of .planning/telemetry/audit.jsonl
• Filter entries that match the campaign slug or its active period
• If none: note "No audit telemetry found for this campaign"

Step 3: FLUSH

Extract raw findings and write to staging.

For campaign sources:

Extract four categories:

A. Successful Patterns — approaches that demonstrably worked (phases completed without rework, postmortem positives, no reverts). Per pattern: name, mechanism (what caused success), evidence (phase/commit/entry), topic (infer from subject matter), applicability.

B. Anti-patterns — what was tried and failed (rework phases, circuit breaker trips, quality gate blocks, reverts). Per pattern: name, what-was-tried, failure-mode, evidence, topic, avoidance.

C. Key Decisions — from Decision Log or inferred from phase descriptions. Per decision: what, rationale, outcome (completed or rework).

D. Quality Rule Candidates — only generate if: specific regex, applies to a specific file pattern, occurred more than once or was severe. Per candidate: regex, file pattern, trigger message, confidence (high/medium/low — skip low).

For evolve sources:

Parse the pattern library's sections. For each pattern record:

• name: section heading
• mechanism: "Mechanism:" field
• delta: "Delta:" field
• topic: infer from "Axis class:" (e.g., orientation_precision → skill-orientation)
• applies-to: "Applies to:" field
• confidence: "Confidence:" field
• evidence: source file + cycle number

Staging write:

Create .planning/wiki/_staging/ if it does not exist. Write staged findings to .planning/wiki/_staging/{source-slug}-{timestamp}.jsonl — one JSON record per finding (newline-delimited).

If zero findings are extractable: write staging file with a single {"type":"empty","source":"{slug}"} record and note "Campaign may have been too brief."

Step 4: COMPILE

Integrate staged findings into wiki pages.

Create .planning/wiki/ if it does not exist.

For each staged finding:

1. Determine the wiki page: .planning/wiki/{topic}.md where topic is the finding's topic field (normalized to kebab-case).
2. Read the wiki page if it exists.
3. If the page exists and contains a section for this pattern (match on ## {name}):
   • Append the new source to the **Evidence:** list
   • Update **Last confirmed:** to today
   • If new confidence >= existing confidence: raise it
   • If new evidence contradicts the existing mechanism: add a **Conflict:** field — do not silently overwrite
4. If the page exists but has no section for this pattern:
   • Append a new section with the full finding
5. If the page does not exist:
   • Create it with the frontmatter template (see below) and the finding as the first section

Wiki page format:

---
topic: {slug}
last-compiled: {ISO date}
sources: {N}
---

# {Topic Title}

## {Pattern Name}
**Mechanism:** {what causes success/failure}
**Evidence:** {source-1 (date)}, {source-2 (date)}, ...
**Confidence:** high/medium/low
**Last confirmed:** {ISO date}
**Applies to:** {scope}

After compiling all findings: update .planning/wiki/index.md — one line per wiki page: - [{topic}]({topic}.md) — {one-line description}. Create index.md if it does not exist.

Step 5: LINT

Scan all .planning/wiki/*.md pages (skip index.md).

Contradiction check: For each page, if two sections contain opposing directives ("always X" vs "never X", "prefer X" vs "avoid X"), flag as: CONFLICT: [{page}] {section-A} contradicts {section-B} — requires human resolution

Staleness check: Sections with **Last confirmed:** older than 60 days are flagged as: STALE: [{page}] {section} — last confirmed {date}, consider re-testing

Coverage check: Warn if a wiki page has fewer than 2 sections — single-entry pages are fragile.

Lint results are reported in the summary. Lint does not modify wiki pages.

Step 5.5: COMPILE SEMANTIC MEMORY BLOCKS

Run a safe deterministic memory compile pass:

node scripts/memory-compile.js compile

This writes compact semantic blocks to .planning/memory/blocks/ and updates .planning/memory/index.json. Blocks must include id, type, scope, owner, confidence, last_verified, sources, and body. Compile only source-supported categories; absent categories and zero blocks are valid. Default context listing excludes stale/unverified records, including digestless legacy notes.

For lint-only memory checks, run:

node scripts/memory-compile.js lint

For agent context loading, use scoped listing instead of rereading full histories:

node scripts/memory-compile.js list --scope verification
node scripts/memory-compile.js list --query "Fleet readiness"

Memory block lint must pass before calling the compile successful. Missing source paths, changed or unverified source bytes, stale blocks, and contradictions are reported as actionable failures.

Step 6: APPEND QUALITY RULES

.claude/harness.json is Citadel's shared configuration path for every runtime, including Codex. Create that path when it is missing; do not substitute a runtime-specific config file.

For each high/medium-confidence rule candidate in the staged findings:

1. Read .claude/harness.json (create with {} if missing)
2. Initialize qualityRules.custom to [] if absent
3. Skip if a rule with the same pattern already exists
4. Append: { "name": "auto-{slug}-{N}", "pattern": "{regex}", "filePattern": "{glob}", "message": "Learned from {slug}: {message}" }
5. Write updated harness.json

Skip low-confidence rules.

Step 7: OUTPUT SUMMARY

For the optional promotion in the summary, Codex uses AGENTS.md. Claude Code uses CLAUDE.md when the project has one; where its AGENTS.md capability is available, the default uses AGENTS.md if no project CLAUDE.md exists. The operator can configure Claude Code to load both under Project instructions. Check the active setting or startup notice before choosing a file, and do not duplicate a rule into an instruction file the runtime is not loading. Preserve user-authored guidance.

=== /learn: {Source} ===
Mode: {campaign | evolve-{target} | lint-only | compile-only}
Sources: {campaign path | evolve path} | postmortem {path or "not found"} | {N} audit entries
Staged: {N} findings → .planning/wiki/_staging/{file}
Compiled: {N} patterns integrated | {M} new wiki sections | {K} existing sections updated
Wiki pages: .planning/wiki/{topic-1}.md, ...
Lint: {conflicts found | clean} | {stale entries} | {coverage warnings}
Memory blocks: {N} compiled | lint {PASS|FAIL} | .planning/memory/index.json
Rules added to harness.json: {M} ({K} skipped — already exist)
Next: review .planning/wiki/index.md — promote stable patterns to the project's active instruction file(s).

Fringe Cases

No completed campaigns: Output message and stop.

.planning/ does not exist: Bare /learn follows Step 1's "No completed campaigns found" response and stops without creating files. Other invocation forms output "Run /do setup first to initialize the harness state directory." Stop.

No Decision Log: Extract decisions from phase descriptions; note "inferred from phase descriptions."

harness.json missing: Create with only the qualityRules section; do not invent other fields.

Duplicate quality rule: Skip silently; count in "skipped — already exist."

Postmortem missing: Proceed without it; note in summary.

Large telemetry file: Read last 200 lines only.

Zero extractable findings: Write staging file noting source was empty. Do not skip wiki/index update.

Wiki page conflict detected at compile time: Add a **Conflict:** field to the section. Never silently overwrite the existing mechanism.

Memory compile has missing sources: Report the missing source paths and keep the existing memory blocks untouched until the source issue is resolved.

Doc-sync queue empty: Output "No doc-sync work is queued." Stop.

Doc-sync queue has only surfaced entries: Output "All doc-sync items are already surfaced." Stop.

evolve pattern-library.md missing: "No evolve pattern library for '{target}'. Run /evolve {target} first to generate patterns." Stop.

Contextual Gates

Disclosure: "Compiling findings into .planning/wiki/. Modifies wiki pages in-place; creates staging files." Reversibility: green — all writes are to .planning/wiki/ and .planning/wiki/_staging/; git restore .planning/wiki/ or delete the directory to undo. Quality rule additions to harness.json can be manually removed. Trust gates:

• Any: run on any completed campaign or evolve target

Quality Gates

• Never invent patterns not supported by evidence in the source files
• Never write a quality rule with confidence < medium
• Never duplicate an existing quality rule (check before appending)
• Wiki index must be updated on every compile run
• Lint must run after every compile (not skipped)
• Memory block lint must pass after --memory or the Step 5.5 compile pass
• /learn --doc-sync must leave no pending or needs-review entries for processed queue items unless run with --dry-run
• Conflicts must be flagged, never silently resolved
• Summary output must include counts for all phases

Exit Protocol

/learn does not produce a full HANDOFF block (it is a utility, not a campaign). It outputs the summary block in Step 7 and waits for the next command.