retro

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Retro Knowledge Skill

Retro Knowledge 技能

Operator Context

操作上下文

This skill wraps

scripts/learning-db.py

into a user-friendly interface for the learning system. The learning database is the single source of truth — there are no L1/L2 markdown files.

本Skill将

scripts/learning-db.py

封装为学习系统的用户友好交互界面。学习数据库是唯一可信数据源——不再使用L1/L2标记文件。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终适用）

DB is the source of truth: All queries go through
```
python3 ~/.claude/scripts/learning-db.py
```
; never maintain a parallel file store
Graduate requires confirmation: Always present proposals and wait for user approval before editing agent/skill files
Graduate requires specificity: Only graduate entries that encode non-obvious, actionable knowledge — never generic advice

数据库为唯一可信源：所有查询均通过
```
python3 ~/.claude/scripts/learning-db.py
```
执行；绝不维护并行文件存储
升级需确认：在编辑agent/skill文件前，必须先展示升级方案并等待用户批准
升级需具备特异性：仅升级包含非通用、可执行知识的条目——绝不升级泛型建议

Default Behaviors (ON unless disabled)

默认行为（启用状态，除非禁用）

Formatted Output: Present results in readable tables/sections, not raw JSON
Actionable Suggestions: When showing stats, suggest next actions (search, graduate)

格式化输出：以易读的表格/分段形式展示结果，而非原始JSON
可执行建议：显示统计数据时，提供后续操作建议（搜索、升级）

Optional Behaviors (OFF unless enabled)

可选行为（禁用状态，除非启用）

Auto-Fix: Apply graduation without confirmation (only if user passes
```
--auto
```
)

自动修复：无需确认即可完成升级（仅当用户传入
```
--auto
```
参数时生效）

What This Skill CAN Do

本Skill可实现的功能

Show learning system stats (entry counts, categories, confidence distribution)
List all entries with filtering by category/confidence
Full-text search across all learnings (FTS5)
Graduate mature entries into specific agents/skills (LLM-driven)
Mark entries as graduated after embedding

显示学习系统统计数据（条目数量、分类、置信度分布）
按分类/置信度筛选列出所有条目
对所有知识进行全文搜索（基于FTS5）
将成熟条目升级为特定agents/skills（由LLM驱动）
嵌入后标记条目为已升级

What This Skill CANNOT Do

本Skill无法实现的功能

Record new learnings (use
```
learning-db.py record
```
directly or let hooks capture)
Auto-graduate without human approval
Generate L1/L2 markdown files (legacy system, removed in ADR-006)

记录新知识（直接使用
```
learning-db.py record
```
命令或由钩子自动捕获）
无需人工批准自动升级
生成L1/L2标记文件（旧系统，已在ADR-006中移除）

Instructions

使用说明

Parse the user's argument to determine the subcommand. Default to

status

if no argument given.

Argument	Subcommand
(none), status	status
list	list
search TERM	search
graduate	graduate

解析用户参数以确定子命令。若未提供参数，默认使用

status

子命令。

参数	子命令
无参数, status	status
list	list
search TERM	search
graduate	graduate

Subcommand: status

子命令：status

Show learning system health summary.

Step 1: Get stats.

bash

python3 ~/.claude/scripts/learning-db.py stats

Step 2: Present status report.

LEARNING SYSTEM STATUS
======================

Entries:     [total] ([high-conf] high confidence)
Categories:  [breakdown by category]
Graduated:   [N] entries embedded in agents/skills

Injection:
  Hook: retro-knowledge-injector.py (DB-backed, FTS5 search)
  Gate: work-intent + keyword relevance

Next actions:
  /retro list              — see all entries
  /retro search TERM       — find specific knowledge
  /retro graduate          — embed mature entries into agents

显示学习系统健康状况摘要。

步骤1：获取统计数据。

bash

python3 ~/.claude/scripts/learning-db.py stats

步骤2：展示状态报告。

学习系统状态
======================

条目总数:     [total]（其中[high-conf]条为高置信度）
分类分布:  [按分类细分]
已升级条目:   [N]条已嵌入agents/skills

注入机制:
  钩子: retro-knowledge-injector.py（基于数据库，支持FTS5搜索）
  网关: 工作意图 + 关键词相关性

后续操作建议:
  /retro list              — 查看所有条目
  /retro search TERM       — 搜索特定知识
  /retro graduate          — 将成熟条目嵌入agents

Subcommand: list

子命令：list

Display all accumulated knowledge.

Step 1: Query all entries.

bash

python3 ~/.claude/scripts/learning-db.py query

Step 2: Present grouped by category:

LEARNING DATABASE
=================

展示所有已积累的知识。

步骤1：查询所有条目。

bash

python3 ~/.claude/scripts/learning-db.py query

步骤2：按分类分组展示：

学习数据库
=================

[Category] ([N] entries)

[分类]（共[N]条）

[topic/key] (conf: [N], [Nx] observations): [first line of value] ...


Optional flags:
- `--category design` — filter to one category
- `--min-confidence 0.7` — only high-confidence entries

[主题/关键词]（置信度: [N], 观测次数: [Nx]）: [内容首行] ...


可选参数:
- `--category design` — 筛选指定分类
- `--min-confidence 0.7` — 仅显示高置信度条目

Subcommand: search

子命令：search

Full-text search across all learnings.

Step 1: Run FTS5 search.

bash

python3 ~/.claude/scripts/learning-db.py search "TERM"

Step 2: Present results ranked by relevance:

SEARCH: "TERM"
==============

[N] results:

1. [topic/key] (conf: [N], category: [cat])
   [value excerpt]

2. ...

对所有知识进行全文搜索。

步骤1：执行FTS5搜索。

bash

python3 ~/.claude/scripts/learning-db.py search "TERM"

步骤2：按相关性排序展示结果：

搜索关键词: "TERM"
==============

共[N]条结果:

1. [主题/关键词]（置信度: [N], 分类: [cat]）
   [内容摘录]

2. ...

Subcommand: graduate

子命令：graduate

Evaluate learning.db entries and embed mature ones into agents/skills. This is LLM work — graduation requires judgment about target identification, edit placement, and phrasing as prescriptive instruction.

Step 1: Get graduation candidates from the DB.

bash

python3 ~/.claude/scripts/learning-db.py query --category design --category gotcha

Skip categories

error

and

effectiveness

— those are injection-only (useful in context but not suitable as permanent agent instructions).

Step 2: For each entry, evaluate graduation readiness.

For each candidate, the LLM:

Reads the learning value
Searches the repo for the target file (grep for related keywords)
Determines edit type: add anti-pattern, add to operator context, add warning, or "not ready / keep injecting"
Checks if the target already contains equivalent guidance

Question	Pass	Fail
Is this specific and actionable?	"sync.Mutex for multi-field state machines"	"Use proper concurrency"
Is this universally applicable?	Applies across the domain	Only applied in one feature
Would it be wrong as a prescriptive rule?	Safe as default	Has important exceptions
Does the target already contain this?	Not present	Already equivalent

Step 3: Present graduation plan to user.

GRADUATION CANDIDATES (N of M entries)

1. [topic/key] → [target file] (add anti-pattern)
   Proposed: "### AP-N: [title]\n[description]"

ALREADY APPLIED (N entries — mark graduated only)
- [topic/key] — already in [file]

NOT READY (N entries — keep injecting)
- [topic/key] — [reason]

Approve? (y/n/pick numbers)

Step 4: On user approval, apply changes.

Use the Edit tool to insert graduated content into target agent/skill files.

After embedding, mark the entry as graduated:

bash

python3 ~/.claude/scripts/learning-db.py graduate TOPIC KEY "target:file/path"

Graduated entries stop being injected (the injector filters

graduated_to IS NULL

Step 5: Report.

GRADUATED:
  [key] → [target file] (section: [section])

Entries marked. They will no longer be injected via the hook
since they are now part of the agent's permanent knowledge.

评估learning.db中的条目，并将成熟条目嵌入agents/skills。此步骤需LLM处理——升级过程需判断目标文件、编辑位置，并将内容改写为规范性指令。

步骤1：从数据库获取升级候选条目。

bash

python3 ~/.claude/scripts/learning-db.py query --category design --category gotcha

跳过

error

和

effectiveness

分类——这些仅用于上下文注入（在上下文环境中有用，但不适合作为永久agent指令）。

步骤2：评估每个条目的升级就绪度。

对每个候选条目，LLM需完成：

读取知识内容
在代码库中搜索目标文件（通过grep查找相关关键词）
确定编辑类型：添加反模式说明、添加到操作上下文、添加警告，或“未就绪/继续注入”
检查目标文件是否已包含等效指导

评估问题	通过	不通过
是否具体且可执行？	"sync.Mutex用于多字段状态机"	"使用正确的并发机制"
是否具有普遍适用性？	适用于整个领域	仅适用于单个功能
作为规范性规则是否存在问题？	可安全作为默认规则	存在重要例外情况
目标文件是否已包含此内容？	未包含	已包含等效内容

步骤3：向用户展示升级方案。

升级候选条目（共M条中的N条）

1. [主题/关键词] → [目标文件]（添加反模式说明）
   建议内容: "### AP-N: [标题]\n[描述]"

已生效条目（共N条——仅标记为已升级）
- [主题/关键词] — 已存在于[文件]中

未就绪条目（共N条——继续注入）
- [主题/关键词] — [原因]

是否批准？(y/n/选择条目编号)

步骤4：获得用户批准后，执行修改。

使用编辑工具将升级内容插入目标agent/skill文件。

嵌入完成后，标记条目为已升级：

bash

python3 ~/.claude/scripts/learning-db.py graduate TOPIC KEY "target:file/path"

已升级条目将停止被注入（注入器会过滤

graduated_to IS NULL

的条目）。

步骤5：完成报告。

已完成升级:
  [关键词] → [目标文件]（章节: [section]）

条目已标记。由于已成为agent永久知识的一部分，它们将不再通过钩子注入。

Examples

示例

Example 1: Quick health check

示例1：快速健康检查

User says: "/retro" Actions: Run

learning-db.py stats

, show entry counts, injection health.

用户输入: "/retro" 操作: 执行

learning-db.py stats

，展示条目数量、注入机制健康状况。

Example 2: See what we know

示例2：查看所有已积累知识

User says: "/retro list" Actions: Run

learning-db.py query

, display grouped by category.

用户输入: "/retro list" 操作: 执行

learning-db.py query

，按分类分组展示。

Example 3: Search for specific knowledge

示例3：搜索特定知识

User says: "/retro search routing" Actions: Run

learning-db.py search "routing"

, display ranked results.

用户输入: "/retro search routing" 操作: 执行

learning-db.py search "routing"

，按相关性排序展示结果。

Example 4: Graduate mature knowledge

示例4：升级成熟知识

User says: "/retro graduate" Actions: Query design/gotcha entries, evaluate each against graduation criteria, propose edits to target agents/skills, apply approved changes, mark graduated.

用户输入: "/retro graduate" 操作: 查询design/gotcha分类条目，按升级标准评估每个条目，提出对目标agents/skills的编辑建议，执行已批准的修改，标记条目为已升级。

Error Handling

错误处理

Error: "learning.db not found"

错误: "learning.db not found"

Cause: Database not initialized yet Solution: Report that no learnings exist yet. Hooks auto-populate during normal work.

原因: 数据库尚未初始化解决方案: 告知用户当前无任何知识积累，钩子会在日常工作中自动填充数据库。

Error: "No graduation candidates"

错误: "No graduation candidates"

Cause: No design/gotcha entries, or all already graduated Solution: Report the stats and suggest recording more learnings via normal work.

原因: 无design/gotcha分类条目，或所有条目已完成升级解决方案: 展示统计数据，并建议通过日常工作积累更多知识。

Anti-Patterns

反模式

Anti-Pattern 1: Graduating Generic Advice

反模式1：升级泛型建议

What it looks like: Graduating "use proper error handling" into the Go agent Why wrong: Generic advice adds noise. Agents already know general patterns. Do instead: Only graduate specific, actionable findings that encode something non-obvious.

表现：将“使用正确的错误处理”升级到Go agent中问题：泛型建议会增加冗余信息，Agent已掌握通用模式 正确做法：仅升级包含具体、可执行的非通用发现的条目。

Anti-Pattern 2: Graduating Without Checking Target

反模式2：未检查目标文件就升级

What it looks like: Proposing to add knowledge that's already in the target file Why wrong: Creates duplication and maintenance burden Do instead: Always grep the target file for equivalent guidance before proposing.

表现：提议添加已存在于目标文件中的知识问题：会造成重复内容和维护负担 正确做法：提出升级建议前，始终通过grep检查目标文件是否已包含等效指导。

Anti-Pattern 3: Auto-Graduating Without User Approval

反模式3：无需用户批准自动升级

What it looks like: Embedding knowledge into agents without showing proposals first Why wrong: Graduation permanently changes agent behavior. Human judgment required. Do instead: Always present proposals and wait for explicit approval.

表现：未展示升级方案就直接将知识嵌入agents 问题：升级会永久改变Agent行为，必须经过人工判断 正确做法：始终先展示升级方案，等待用户明确批准后再执行。