Review learning

Review agent learning

Treat captured events as evidence, not truth. Never infer missing business facts or silently modify project knowledge or another skill.

Review workflow

1. Stay in the observed project's working directory. Run node "${CLAUDE_PLUGIN_ROOT}/runtime/cli.mjs" doctor --project-root . if runtime or storage health is uncertain. Verify that projectRoot is the observed project, not the plugin source directory; otherwise rerun with the observed project's absolute path.
2. Read the relevant source candidate file .agent-learning/candidates/<session_id>.jsonl. Do not treat .review.jsonl files as source candidates; they contain prior decisions.
3. Follow each candidate's event sequence into .agent-learning/ledger/raw/<session_id>.jsonl.
4. Classify each candidate as confirmed, dismissed, or unresolved. Preserve the original record. Record every decision with node "${CLAUDE_PLUGIN_ROOT}/runtime/cli.mjs" record-review --project-root . --session-id "<session_id>" --candidate-id "<candidate_id>" --status <confirmed|dismissed|unresolved> --reviewer "<reviewer>" --notes "<concise reason>". Confirmed reviews must also pass --expected-behavior "<json array>" containing the machine-checkable behaviors that define a correct outcome. A candidate can only be reviewed once; pass --force to append a new decision deliberately. Do not construct or write the review path directly. The command appends to the exact sibling path .agent-learning/candidates/<session_id>.review.jsonl.
5. For confirmed items, identify the earliest observable deviation. Separate observed evidence from inferred cause.
6. Group related confirmed items into one Episode only when they share the same task and causal issue.
7. Write episodes to .agent-learning/episodes/LE-<date>-<sequence>.json using schemas/episode.schema.json.
8. Propose follow-ups independently:
   • Missing project fact: knowledge candidate.
   • Existing fact was not retrieved: retrieval/context change.
   • Agent continued without evidence: process gate change.
   • No unique answer existed: decision record.
   • Wrong output escaped the workflow: eval or verification change.
9. Turn confirmed items into runnable regression cases: node "${CLAUDE_PLUGIN_ROOT}/runtime/cli.mjs" export-evals --project-root . --format yaml,json, then node "${CLAUDE_PLUGIN_ROOT}/runtime/cli.mjs" run-evals --project-root . --validate, then node "${CLAUDE_PLUGIN_ROOT}/runtime/cli.mjs" run-evals --project-root . --ci. The canonical cases live at .agent-learning/evals/evals.jsonl; reusable YAML/JSON exports live under evals/export/. Cases whose anchors cannot discriminate correct from incorrect behavior are reported invalid and excluded from the CI gate.
10. After writing or archiving episodes, rebuild the retrieval index with node "${CLAUDE_PLUGIN_ROOT}/runtime/cli.mjs" memory-rebuild --project-root .. Session-time injection only happens when the project config sets memory.enabled: true.
11. For repository-level cases, capture the current project state with node "${CLAUDE_PLUGIN_ROOT}/runtime/cli.mjs" snapshot --project-root . (or enable capture.evalSnapshot for automatic capture) and attach eval.setup.files/eval.setup.commands to the episode so run-evals --worktree can reproduce it.
12. Create an eval candidate only for observable behavior. Test whether the agent detects, retrieves, verifies, stops, or asks correctly; do not create a memory quiz.

Capture diagnosis

• Interpret doctor.ok: true only as runtime and storage health. It does not prove that a Hook was registered or executed.
• Treat raw ledger records as proof that capture executed successfully.
• Treat a displayed Hook error, such as Stop hook error, as proof that the Hook was registered and invoked but its command failed.
• Do not inspect project or user settings to decide whether plugin-bundled Hooks are registered. Plugins loaded with --plugin-dir register hooks/hooks.json dynamically and need not add settings entries.
• If there are no raw records and no Hook errors, report registration/execution as unknown and ask for Claude Code debug logs. Do not claim that settings registration is required.
• If Node reports Cannot find module 'C:\Program Files\Git\runtime\hook.mjs', diagnose a host that cannot resolve the plugin-root placeholder in shell form.
• If Node reports [stdin]:1, Unexpected token ':', diagnose a host that ignored Hook args and ran bare node, causing stdin event JSON to be parsed as JavaScript.
• For either compatibility error, instruct the user to update or reload the plugin version whose generated Hook command is self-contained and uses neither args nor CLAUDE_PLUGIN_ROOT; do not propose manual settings entries.
• If an older review created <session_id>.review/.jsonl, run node "${CLAUDE_PLUGIN_ROOT}/runtime/cli.mjs" repair-review-paths --project-root . once to migrate it to <session_id>.review.jsonl without changing the records.

Allowed problem categories

• knowledge-missing
• knowledge-not-retrieved
• unsupported-assumption
• skill-process-defect
• human-decision-required
• tool-or-verification-failure
• repeated-failure

Evidence gates

• Treat explicit human correction and deterministic test failure as strong signals, not automatic causal explanations.
• Treat keyword-detected correction as probable until a reviewer confirms what was wrong.
• Do not promote a candidate whose preceding output or correction evidence is missing.
• Do not confirm a review without expected_behavior; free-text notes alone are not a testable standard.
• Quote only the minimum evidence required and preserve its event sequence.
• Redact secrets, personal data, proprietary source, and irrelevant tool output before promoting an Episode.

Review output

Return a concise receipt containing counts for confirmed, dismissed, unresolved, Episodes created, and follow-ups proposed. Highlight any candidate that cannot be resolved without human judgment.