Cognitive Reflection

cognitive-reflection

Overview

This skill upgrades reflection from "append another note" to a compact learning system:

• Knowledge Architecture: observations -> connected hypotheses -> promoted rules
• Decision Journal: compact log of non-obvious decisions, reversals, and costly misses
• Quality Gate: evidence-first promotion criteria so mediocre output does not self-promote

The core idea is simple:

• memory without reflection becomes a growing correction log
• reflection without promotion stays local to one session
• promotion without quality gates turns noise into permanent rules

This skill is the missing meta-layer above the existing reflection checkpoint workflow.

When To Use

• The user provides a note, decision, correction, or failure pattern that should survive across sessions
• A repeated mistake should become a durable rule rather than another diary entry
• You want to inject the three reflection blocks into CLAUDE.md
• You need to score whether a candidate rule is strong enough to promote
• You want a compact decision index inside CLAUDE.md instead of turning it into a long notebook

Use reflection instead when:

• you only need a milestone checkpoint in notes.md / task_plan.md
• you are recording progress, not evolving rules

Core Pattern

1. Retrieve:
   • search existing rules, notes, postmortems, and memory before treating a note as "new"
2. Connect:
   • merge related observations into one candidate rule or decision, instead of storing fragments
3. Evaluate:
   • ask whether the candidate is evidence-backed, reusable, failure-specific, and worth the prompt budget
4. Promote:
   • only then write it into CLAUDE.md as a compact promoted rule + journal entry

Commands

Install or refresh the managed block:

python3 scripts/cognitive_reflection.py install --json
ai skills run cognitive-reflection "install"
ai cognitive-reflection install
ai cognitive-reflection /path/to/project install

Default target behavior:

• no project directory: prefer ~/.claude/CLAUDE.md when it exists
• with project_dir: default to <project_dir>/CLAUDE.md
• explicit --target always wins

Evaluate a candidate decision or lesson:

python3 scripts/cognitive_reflection.py evaluate \
  --project-root . \
  --target CLAUDE.md \
  --note "Pricing test lost users after free tier removal was ignored in onboarding assumptions." \
  --decision "Connect pricing, onboarding, and competitor packaging changes before shipping onboarding changes." \
  --rule "Treat pricing/package changes as onboarding inputs, not separate observations." \
  --failure-mode "isolated observations never turned into a product rule" \
  --json

Promote a rule after it passes the gate:

python3 scripts/cognitive_reflection.py promote \
  --target CLAUDE.md \
  --rule "Treat pricing/package changes as onboarding inputs, not separate observations." \
  --decision "Connect pricing, onboarding, and competitor packaging changes before shipping onboarding changes." \
  --failure-mode "isolated observations never turned into a product rule" \
  --evidence "Repeated observation across notes + user correction + verification pass" \
  --json

What It Is Good At

• keeping CLAUDE.md compact while still making it evolve
• turning corrections into durable, reusable rules
• preventing "smart notebook" behavior where observations never connect
• creating a traceable promotion cycle instead of silent self-congratulation

What It Is Not

• a replacement for raw notes, postmortems, or rolling ledgers
• a generic journaling system
• a guarantee that every observation deserves promotion
• a substitute for tests, metrics, or user correction

Gotchas

• Do not dump raw observations straight into CLAUDE.md; only compact promoted rules and decision summaries belong there.
• A single anecdote is not a rule. If the candidate has weak evidence, keep it as an observation.
• If the same decision already exists in the journal, update or reuse it; do not rename duplicates as "new learning."
• Quality Gate is supposed to reject noise. A rejected promotion is a healthy outcome, not a failure.
• This skill complements reflection; it does not replace milestone checkpoints in notes.md and task_plan.md.

Verification

python3 scripts/cognitive_reflection.py install --target /tmp/CLAUDE.md --json
python3 scripts/cognitive_reflection.py evaluate --project-root . --target CLAUDE.md --note "..." --decision "..." --rule "..." --json
python3 scripts/cognitive_reflection.py promote --target /tmp/CLAUDE.md --rule "..." --decision "..." --failure-mode "..." --json
python3 -m unittest tests.test_cognitive_reflection -v

是什么

cognitive-reflection 用来把 战略圆桌顾问 场景里的任务输入转成可执行的流程、检查清单和交付物。

This skill upgrades reflection from "append another note" to a compact learning system:

它的价值在于让 战略决策线 在 Claude Code、Codex、Gemini、Hermes 或 OpenClaw 中复用同一套岗位能力，而不是依赖一次性的聊天提示词。

怎么用

1. 明确当前任务目标、输入材料、约束和期望交付物，再加载 cognitive-reflection。
2. 按 skill 文档中的流程、检查清单或工具建议执行，优先复用仓库已有规范与真实命令。
3. 把关键判断、风险、验证命令和产出路径记录到当前任务文档或交付说明中。
4. 用最小可证明的检查确认结果有效；发现缺口时回到 skill 清单补齐。

架构图

flowchart LR
  A[任务输入] --> B[加载 cognitive-reflection]
  B --> C[执行流程与检查清单]
  C --> D[生成交付物与风险记录]
  D --> E[验证结果并沉淀复盘]