Use this skill when extracting session patterns into reusable learnings. Three modes: analyze (extract from session history), review (edit/manage existing learnings), list (display active learnings). Manages .orchestrator/metrics/learnings.jsonl.
Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.
Quelldateien prüfen
Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Ein direkter Befehl überspringt den Prüf-Prompt. Prüfen Sie die Quelle, bevor Sie ihn ausführen.
[{"flag":"--apply","description":"Apply dialectic-derived diff to USER.md + AGENT.md"},{"flag":"--dry-run","description":"Show diff without writing (default)"},{"flag":"--model <name>","description":"Override single-pass LLM (haiku|sonnet|opus)"},{"flag":"--budget-tokens <N>","description":"Token budget for derivation prompt (default 8000)"}]
description
Use this skill when extracting session patterns into reusable learnings. Three modes: analyze (extract from session history), review (edit/manage existing learnings), list (display active learnings). Manages .orchestrator/metrics/learnings.jsonl.
Platform Note: State files use the platform's native directory: .claude/ (Claude Code), .codex/ (Codex CLI), or .cursor/ (Cursor IDE). Shared metrics live in .orchestrator/metrics/ (v2) with fallback to <state-dir>/metrics/ for pre-v2.0 legacy data. See skills/_shared/platform-tools.md.
Evolve Skill
Phase 0: Bootstrap Gate
Read skills/_shared/bootstrap-gate.md and execute the gate check. If the gate is CLOSED, invoke skills/bootstrap/SKILL.md and wait for completion before proceeding. If the gate is OPEN, continue to Phase 1.
Do NOT proceed past Phase 0 if GATE_CLOSED. There is no bypass. Refer to `skills/_shared/bootstrap-gate.md` for the full HARD-GATE constraints.
Phase 1: Config & Data Loading
1.1 Read Session Config
Read and parse Session Config per skills/_shared/config-reading.md. Store result as $CONFIG.
1.2 Check Persistence
Extract persistence from $CONFIG. If persistence is false, abort with message:
"Learnings require persistence to be enabled in Session Config. Add persistence: true to your Session Config block (CLAUDE.md for Claude Code, AGENTS.md for Codex CLI)."
1.3 Determine Mode
Read mode from $ARGUMENTS:
If empty or not provided, default to analyze
Valid modes: analyze, review, list, dialectic
If invalid mode provided, report error and list valid modes
1.4 Load Data
Lazy-create defensive (#185): If .orchestrator/metrics/learnings.jsonl does not exist (pre-#185 repo or bootstrap skipped), create an empty file and emit an info log — do NOT hard-fail:
This defensive step is idempotent and cheap — it ensures /evolve analyze|review|list never fails because of a missing artifact file.
Read .orchestrator/metrics/sessions.jsonl (session history). If it does not exist, check <state-dir>/metrics/sessions.jsonl as a legacy fallback (where <state-dir> is .claude/, .codex/, or .cursor/ per platform). If neither exists, warn: "No session history found. Run at least one session first."
Read .orchestrator/metrics/learnings.jsonl if it exists. If not found, check <state-dir>/metrics/learnings.jsonl as a legacy fallback.
Count existing learnings, note any where expires_at < current date (expired)
Phase 2: Mode Dispatch
Route based on mode:
analyze → Phase 3
review → Phase 4
list → Phase 5
dialectic → Phase 6
Phase 3: Analyze Mode (default)
Extract learnings from session history.
Vault Integration: If vault-integration.enabled is true in Session Config, confirmed learnings are mirrored to the configured Obsidian vault after the atomic write (Step 3.5, step 9). See docs/session-config-reference.md for the vault-integration config block.
Step 3.1: Read Session Data
Read all entries from .orchestrator/metrics/sessions.jsonl (or <state-dir>/metrics/sessions.jsonl if the v2 path does not exist — see Phase 1.4 fallback)
Parse each JSONL line as JSON
Sort by completed_at descending (most recent first)
If no sessions found, abort: "No session data available. Complete at least one session before running evolve."
Step 3.2: Pattern Extraction
For each of the 8 learning types, apply these heuristics:
1. fragile-file (type: fragile-file)
Look at wave data: if the same file appears in 3+ waves' files_changed within a session, it is fragile
Cross-session: if a file appears in 3+ different sessions' files_changed, flag it
Subject = file path (relative to project root)
2. effective-sizing (type: effective-sizing)
Compare total_agents and total_waves across session types
Calculate average agents per wave for each session type
Subject = canonical identifier like deep-session-sizing or feature-session-sizing
Insight = "Deep sessions average X agents across Y waves" or "Feature sessions work well with X agents/wave"
3. recurring-issue (type: recurring-issue)
Look at agent_summary — if failed or partial > 0 across multiple sessions, flag
Insight = "File has <error_class> stagnation in recent sessions — candidate for pre-edit grounding (#85)."
Evidence = " sessions with stagnation_events for this file/class"
These learnings feed #85 (pre-edit grounding injection) when it ships — high-frequency pairs trigger grounding.
7. hardware-pattern (type: hardware-pattern)
v3.1.0 / Sub-Epic #160 (C2, issue #171). Keyed on host_class rather than project — surfaces hardware-bound problems that affect the user across every repo on the same machine. Complements the project-keyed types above.
Read .orchestrator/metrics/events.jsonl (session + wave events) and the registry sweep.log at ~/.config/session-orchestrator/sessions/sweep.log. Both are optional — missing files produce no candidates.
Invoke scripts/lib/hardware-pattern-detector.mjs → detectHardwarePatterns({events, sweepLogEntries, thresholds}). Thresholds come from Session Config resource-thresholds when present, falling back to DEFAULT_THRESHOLDS.
Five detection signals (aggregated per (signal, host_class) pair, ≥2 occurrences required):
oom-kill — orchestrator.session.stopped with exit_code: 137 or OOM-marker in error
heartbeat-gap — registry sweep-log entries with gap_minutes above resource-thresholds.zombie-threshold-min
concurrent-session-pressure — session-start events with peer_count ≥ concurrent-sessions-warn
disk-full — events whose error matches ENOSPC / "no space left"
Each candidate is piped through candidateToLearning() → validateLearning(). Default scope is private (in-repo only). To promote to public, the user runs npm run share:hw-learnings -- --promote (C3 export). This anonymizes each private hardware-pattern entry, validates via the privacy contract, and appends a public twin to learnings.jsonl (original preserved). Use --dry-run to preview without writing.
Subject convention: <signal>::<host_class> (e.g., oom-kill::macos-arm64-m3pro). The :: separator avoids colliding with project-keyed subjects.
Confidence starts at 0.5 like other learning types, but decay is slower in practice: hardware stays the same longer than code. This is an emergent property of the existing expire-after-N-days policy applied to a mostly-stable host_class — no special-casing needed.
Presentation in step 3.5 (see below): render hardware-patterns in a dedicated section titled ## Hardware Patterns (keyed on host_class) after the project-keyed patterns. This makes the source of the learning obvious to the user at confirmation time.
v3.2 Autopilot / Sub-Epic #271 (issue #298). Compares manual vs. autopilot session outcomes per mode (housekeeping, feature, deep) so the loop can learn whether walk-away runs preserve quality. Complements the project-keyed and hardware-keyed types above.
Read .orchestrator/metrics/autopilot.jsonl (one record per autopilot loop run) and.orchestrator/metrics/sessions.jsonl (manual + autopilot session outcomes). Both are optional — missing files produce no candidates.
Invoke scripts/lib/evolve/autopilot-effectiveness.mjs → analyze(autopilotRuns, sessions). The module pairs records by mode and compares completion-rate, carryover-rate, kill-switch frequency, and quality-gate pass-rate between the two populations.
Data-gating contract: the analyzer requires ≥20 paired manual+autopilot runs per mode before emitting any candidates. Below that threshold the function returns [] (empty input contract) — evolve simply skips this type for that mode and reports nothing. This prevents premature conclusions from small samples (#297 calibration depends on the same threshold).
Subject convention: <mode>-manual-vs-autopilot (e.g., housekeeping-manual-vs-autopilot, feature-manual-vs-autopilot, deep-manual-vs-autopilot). One subject per mode that crosses threshold.
Insight = "Autopilot sessions complete at % vs. manual % (Δ pp across N pairs)" or analogous carryover/kill-switch framing when those signals dominate.
Confidence starts at 0.5 like other learning types; lifecycle ±0.15 / -0.20 via the existing dedupe-and-update infrastructure in Step 3.3 — no special-casing.
Each candidate is piped through candidateToLearning() → validateLearning() exactly like the other types. Default scope is private (autopilot RUN data is per-host until the user opts in to share). (refs #298)
Step 3.2b: Zero Patterns Check
If no patterns were extracted across all 8 types, report: "No patterns found in session history. This can happen with very few sessions or sessions that lack detailed wave/agent data." and skip to end (do not proceed to AskUserQuestion).
Step 3.3: Deduplicate Against Existing Learnings
For each extracted pattern, check if a learning with same type + subject already exists in learnings.jsonl:
If exists: propose confidence update (+0.15 if confirmed by new evidence, -0.2 if contradicted)
If new: propose as new learning with confidence 0.5
Step 3.4: Present Findings via AskUserQuestion
Present extracted patterns to the user for confirmation. Use AskUserQuestion with multiSelect: true:
On Codex CLI where AskUserQuestion is unavailable, present as a numbered Markdown list.
AskUserQuestion({
questions: [{
question: "Which learnings should be saved?\n\nExtracted patterns from session history:",
header: "Evolve — Confirm Learnings",
options: [
{
label: "[type] subject",
description: "insight | evidence: ... | confidence: 0.5 (new) or +0.15 (update)"
},
...
{
label: "Skip all",
description: "Do not save any learnings this time"
}
],
multiSelect: true
}]
})
If user selects "Skip all" or selects nothing, abort gracefully: "No learnings saved."
Step 3.5: Write Confirmed Learnings
For confirmed learnings, use atomic rewrite strategy:
Read ALL existing lines from .orchestrator/metrics/learnings.jsonl (if exists) into memory. If not found, check <state-dir>/metrics/learnings.jsonl as a legacy fallback. If legacy data is found, it will be migrated to the v2 path on write (step 8).
Apply confidence updates for confirmed existing learnings:
Increment confidence by +0.15
Cap at 1.0
Reset expires_at to current date + learning-expiry-days (default: 30)
Apply confidence decrements for contradicted learnings (-0.2) — do NOT reset expires_at for contradicted learnings (let them decay naturally)
Append new learnings with the canonical schema_version:1 shape — every field is required (#303):
schema_version: 1 (integer, ALWAYS — never omit)
id: UUID v4 string generated via node -e "const {randomUUID}=require('crypto');process.stdout.write(randomUUID())" or uuidgen | tr '[:upper:]' '[:lower:]'. MUST be a non-empty UUID string. Never omit — missing id causes 100% mirror-skip (#303).
type: one of fragile-file, effective-sizing, recurring-issue, scope-guidance, deviation-pattern, stagnation-class-frequency, hardware-pattern, autopilot-effectiveness
subject: the pattern subject
insight: human-readable description of the pattern. MUST be insight — do NOT use description or recommendation (legacy alias keys that vault-mirror cannot read; see #303).
evidence: specific data points that support the pattern
confidence: 0.5 for new learnings
source_session: non-empty kebab-slug string identifying the session from which the pattern was extracted (e.g. main-2026-04-27-1942). MUST be a string — never an object, array, number, or null. If multiple sessions contributed, use the earliest. If unknown, use "unknown" (the string). Never pass String(<object>) — that yields "[object Object]" and breaks the YAML mirror downstream (#307). Optional pre-write validation: jq -e 'select(.source_session | type == "string" and length > 2)'.
created_at: current ISO 8601 date
expires_at: current date + learning-expiry-days (default: 30) (ISO 8601)
Verify write: Read back the first line of the written file to confirm valid JSON. If read-back fails or is not valid JSON, report error to user.
Prune: remove entries where expires_at < current date OR confidence <= 0.0
Consolidate duplicates (NULL-SUBJECT SAFE): if same type + subject appears more than once
AND subject is a non-empty string, keep the entry with highest confidence.
Entries with null/empty/missing subject are NEVER collapsed — each is keyed by its unique id
and always preserved. (Fix for issue #284: empty-subject dedupe collapse.)
Write entire result back to .orchestrator/metrics/learnings.jsonl with > (atomic rewrite, NOT append >>)
Vault mirror (conditional): Check $CONFIG."vault-integration".enabled via jq. If the field is missing or false, skip this step entirely — skill behavior is unchanged.
If enabled is true:
a. Check $CONFIG."vault-integration".mode. If mode is off, skip the mirror invocation (treat as disabled). If mode is absent, default to warn.
b. Resolve the vault directory: use $CONFIG."vault-integration"."vault-dir" if non-null, otherwise fall back to the $VAULT_DIR environment variable. If neither is set, emit a warning and skip.
c. Invoke the mirror script. Derive a synthetic EVOLVE_SESSION_ID so the vault-mirror auto-commit phase (#31) produces a traceable commit subject (chore(vault): mirror evolve-<date> — N learnings + 0 sessions):
warn (default): on non-zero exit, surface a warning in evolve output (e.g. "Warning: vault mirror failed — learnings saved locally but not mirrored.") but do NOT fail the skill.
strict: on non-zero exit, fail the skill immediately and report the error to the user.
e. On success (exit 0), report: "Mirrored N learnings to <vault-dir>/40-learnings/."
Report: "Saved N new learnings, updated M existing. Total active: K."
Phase 4: Review Mode
Interactive management of existing learnings.
Step 4.1: Load Learnings
Read .orchestrator/metrics/learnings.jsonl. If not found, check <state-dir>/metrics/learnings.jsonl as a legacy fallback.
If neither exists or both are empty: "No learnings found. Run /evolve analyze first."
Parse each line as JSON
Step 4.2: Display Learnings
Present a formatted table grouped by type:
## Active Learnings
| # | Type | Subject | Confidence | Expires | Insight |
|---|------|---------|------------|---------|---------|
| 1 | fragile-file | src/lib/auth.ts | 0.80 | 2026-07-05 | Changed in 4 of last 5 sessions |
| 2 | effective-sizing | feature-session-sizing | 0.65 | 2026-06-20 | Feature sessions work well with 3 agents/wave |
| ... | ... | ... | ... | ... | ... |
Summary: N active learnings (M high confidence, K expiring soon)
Step 4.3: Interactive Management
Use AskUserQuestion with options:
On Codex CLI where AskUserQuestion is unavailable, present as a numbered Markdown list.
AskUserQuestion({
questions: [{
question: "What would you like to do with your learnings?",
header: "Evolve — Review",
options: [
{ label: "Boost confidence", description: "Select learnings to boost (+0.15)" },
{ label: "Reduce confidence", description: "Select learnings to reduce (-0.2)" },
{ label: "Delete specific learnings", description: "Select learnings to remove" },
{ label: "Extend expiry", description: "Reset expires_at by learning-expiry-days from now" },
{ label: "Done — no changes", description: "Exit without changes" }
]
}]
})
If user selects "Boost confidence", "Reduce confidence", "Delete specific learnings", or "Extend expiry", present a follow-up AskUserQuestion with multiSelect: true listing all learnings by # | type | subject so the user can select which ones to modify.
On Codex CLI where AskUserQuestion is unavailable, present as a numbered Markdown list.
Step 4.4: Apply Changes
Use the same atomic rewrite strategy as Phase 3, Step 3.5:
Read all lines from learnings.jsonl
Apply the selected operation to selected learnings:
Boost: +0.15 confidence (cap 1.0), reset expires_at to +learning-expiry-days
Reduce: -0.2 confidence
Delete: remove selected entries
Extend: reset expires_at to current date + learning-expiry-days
Prune entries where expires_at < current date OR confidence <= 0.0
Consolidate duplicates (same type + non-empty subject): keep highest confidence.
Null-subject entries are preserved individually (keyed by id). See SKILL.md #284 fix note.
Write entire result back with > (atomic rewrite)
Report: "Updated N learnings. Total active: K."
Phase 5: List Mode
Simple read-only display.
Step 5.1: Load and Display
Read .orchestrator/metrics/learnings.jsonl. If not found, check <state-dir>/metrics/learnings.jsonl as a legacy fallback.
If neither exists: "No learnings yet. Run /evolve analyze to extract patterns from session history."
Parse each line as JSON
Step 5.2: Formatted Output
Display a formatted table grouped by type:
## Active Learnings
### fragile-file
| Subject | Confidence | Expires | Insight |
|---------|------------|---------|---------|
| ... | ... | ... | ... |
### effective-sizing
| Subject | Confidence | Expires | Insight |
|---------|------------|---------|---------|
| ... | ... | ... | ... |
(repeat for each type that has entries)
Step 5.3: Summary
Display summary line:
N active learnings (M high confidence, K expiring soon)
High confidence = confidence > 0.7
Expiring soon = expires_at within 14 days of current date
Phase 6: Dialectic Mode
Single-pass LLM derivation of USER.md + AGENT.md (peer cards from #503) updates from current learnings + sessions + steering files. Dry-run-default per #506 EARS contract.
Step 6.0: Argument Parsing
Parse $ARGUMENTS for trailing flags after the dialectic keyword:
Flag
Default
Behavior
--apply
false
Write diff to USER.md/AGENT.md via merger.mjs; without it = dry-run
--dry-run
true
Explicit dry-run (default); mutually exclusive with --apply
--model <name>
from Session Config dialectic.model (default haiku)
Override LLM
--budget-tokens <N>
from Session Config dialectic.budget-tokens (default 8000)
Cadence check: if invoked via session-end Phase 3.6.7 auto-trigger, the trigger has already pre-checked cadence. For manual invocation, skip cadence — manual always runs.
Step 6.2: Data Load
Read all 4 input sources via runDialecticDeriver() from scripts/dialectic-deriver.mjs (see W2 I1):
Top-N learnings from .orchestrator/metrics/learnings.jsonl (default 50, sorted by confidence DESC)
Last-K sessions from .orchestrator/metrics/sessions.jsonl (default 10, sorted by completed_at DESC)
Peer cards via readPeerCards(repoRoot) from scripts/lib/peer-cards/reader.mjs — returns {user, agent} or null
Graceful degradation: any null/empty source is acceptable. If ALL inputs empty → return {status: 'empty-input'}.
Step 6.3: Dispatch the Deriver Agent
Construct a dispatchAgent function that uses the harness Agent tool to invoke the dialectic-deriver agent (see agents/dialectic-deriver.md):
constdispatchAgent = async ({ model, prompt, maxTokens }) => {
// Coordinator uses Agent tool with subagent_type: "session-orchestrator:dialectic-deriver"// and the model parameter to invoke the right tierconst result = awaitAgent({
description: "Dialectic-deriver LLM pass",
subagent_type: "session-orchestrator:dialectic-deriver",
model,
prompt,
});
return { text: result.text, usage: result.usage ?? { input_tokens: 0, output_tokens: 0 } };
};
> **Why`maxTokens` is not passed to Agent():** the ClaudeCode harness `Agent()` tool does not currently accept a `max_tokens` parameter. Output-token budget is therefore enforced via prompt text (see line 414in`skills/session-end/SKILL.md`: "with budget ${budget-tokens} input + 4000 output tokens"). The dispatchAgent contract declares `maxTokens`as the canonical interface; the evolve skill destructures it for forward-compat but routes enforcement through the prompt body. When the harness adds a max_tokens hint, this dispatchAgent becomes the single update point.
const result = awaitrunDialecticDeriver({
dispatchAgent,
repoRoot: process.cwd(),
model: argv.model ?? config.dialectic?.model ?? 'haiku',
budget: { input: argv['budget-tokens'] ?? config.dialectic?.['budget-tokens'] ?? 8000, output: 4000 },
dryRun: !argv.apply,
allowEmptying: argv['allow-emptying'] ?? false,
});
Step 6.4: Diff Output & Apply Gate
If dry-run (default): present diff inline; write to .orchestrator/dialectic-pending.md (atomic tmp+rename); EXIT. Suggestion: "Re-run with /evolve --dialectic --apply to apply."
If --apply: call mergePeerCard(existingBody, managedUpdates) from scripts/lib/peer-cards/merger.mjs for each card target, then writePeerCard(repoRoot, 'user', mergedUserCard) and writePeerCard(repoRoot, 'agent', mergedAgentCard) from scripts/lib/peer-cards/writer.mjs. Update the updated: frontmatter.
Report: Dialectic-derived: M deltas to USER.md, N deltas to AGENT.md. Dry-run | Applied. Tokens: in=<X> out=<Y>.
Step 6.5: Error Handling
status: 'unknown-model' → fail with clear error (already thrown by validateModel)
status: 'budget-exceeded' → emit {status:'budget-exceeded', used:N, budget:M}, do NOT truncate
status: 'would-empty-card' → warn + require --allow-emptying flag
status: 'empty-input' → exit clean with message "dialectic: skipped (no input)"
subagent crash → log ⚠, exit cleanly (do NOT write to .orchestrator/dialectic-pending.md)
Cross-reference: PRD #506 AC1-AC4 + EARS gates. Vault Integration: dialectic does NOT mirror to vault (#506 scope — peer cards are repo-local by design; vault mirror is for cross-repo sessions/learnings).
Critical Rules
NEVER modify learnings.jsonl without reading it first — race condition prevention
NEVER skip the deduplication check — duplicates degrade the intelligence system
NEVER write learnings without user confirmation — always present via AskUserQuestion first (on Codex CLI where AskUserQuestion is unavailable, present as a numbered Markdown list)
ALWAYS use uuid-v4 for new learning IDs (generate via uuidgen or equivalent bash command)
ALWAYS set expires_at to current date + learning-expiry-days from config (default: 30) for new learnings
ALWAYS present findings to user before writing — no silent writes
ALWAYS use atomic rewrite (read all, modify, write all with >) — never append with >>
ALWAYS cap confidence at 1.0 — never exceed
Anti-Patterns
DO NOT write learnings without user confirmation — always present via AskUserQuestion first (on Codex CLI where AskUserQuestion is unavailable, present as a numbered Markdown list)
DO NOT append to learnings.jsonl — always use atomic rewrite (read all, modify, write all)
DO NOT create duplicate learnings — always check type + subject match first
DO NOT set confidence above 1.0 or forget to cap it
DO NOT fabricate patterns — only extract from actual session data with verifiable evidence
DO NOT skip the pruning step — expired and zero-confidence entries must be removed on every write
