Back to Details

distill

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Distill

知识提炼

Purpose

目的

Extract reusable knowledge from closed tasks and archive their context directories. Operates on closed beads, leveraging session linkage to pull full work history.
从已关闭的bead中提取可复用知识，并归档其上下文目录。基于已关闭的bead运行，利用会话关联拉取完整工作历史。

When to Use

使用场景

  • User says "distill", "archive", "review closed tasks"
  • Periodic knowledge extraction from completed work
  • Before a project retrospective
  • 用户说出“distill”、“archive”、“review closed tasks”
  • 定期从已完成工作中提取知识
  • 项目回顾会前

Process

流程

Step 1: Find Candidates

步骤1：寻找候选对象

bash
bd query "status=closed AND NOT label=distilled" -a
Show the list to the user. If specific bead IDs were provided, use those instead.
bash
bd query "status=closed AND NOT label=distilled" -a
将列表展示给用户。如果用户提供了特定的bead ID，则使用这些ID。

Step 2: Select Scope

步骤2：选择范围

Ask the user which beads to distill, or confirm "all" if the list is small (<=5).
询问用户要提炼哪些bead，如果列表较小（<=5个），则确认是否“全部”提炼。

Step 3: Per Bead — Gather Context

步骤3：逐个Bead — 收集上下文

For each selected bead:
  1. bd show <id> --json
    — get description, close_reason, sessions, metadata
  2. Check for context dir: 
    projects/<project>/contexts/<bead-id>/
    — read notes.md and any artifacts
  3. Identify the project from the bead's labels
对于每个选中的bead：
  1. bd show <id> --json
    — 获取描述、关闭原因、会话、元数据
  2. 检查上下文目录：
    projects/<project>/contexts/<bead-id>/
    — 读取notes.md及任何工件
  3. 从bead的标签中确定所属项目

Step 4: Per Bead — Extract Knowledge

步骤4：逐个Bead — 提取知识

Review gathered context and identify:
  • Reusable patterns — workflows, techniques, approaches that worked
  • Decisions made — architectural choices, tradeoffs, rationale
  • Preset candidates — conventions or practices that should be codified in CLAUDE.md Presets
  • Time-sink patterns — what took the most time, could it be automated?
  • Workflow gaps — places where configured workflows were not followed (see Step 6)
  • Interruption signals — see Step 4a
  • User suggestions — see Step 4b
回顾收集到的上下文，识别：
  • 可复用模式 — 有效的工作流、技术、方法
  • 已做决策 — 架构选择、权衡、理由
  • 预设候选 — 应在CLAUDE.md Presets中编纂的约定或实践
  • 耗时模式 — 最耗时的工作，是否可自动化？
  • 工作流缺口 — 未遵循已配置工作流的地方（见步骤6）
  • 中断信号 — 见步骤4a
  • 用户建议 — 见步骤4b

Step 4a: Interruption Analysis

步骤4a：中断分析

Manual interruptions (user hit Ctrl+C, said "stop", "wait", "no", redirected mid-task) are high-signal events. They mean the agent was doing something the user didn't want. For each interruption found:
  1. What was the agent doing? — the action that got interrupted
  2. Why did the user interrupt? — wrong direction, too slow, unnecessary work, wrong approach, scope creep
  3. What happened after? — did the user redirect to a different approach? Give up on the task?
  4. Root cause — classify as one of:
    • Missing knowledge — agent didn't know something it should have (→ add to shared context or presets)
    • Wrong default — agent chose a reasonable-sounding but incorrect approach (→ add preset or skill guidance)
    • Scope creep — agent expanded beyond what was asked (→ note as over-engineering pattern)
    • Tool misuse — agent used the wrong tool or approach (→ update skill or add to presets)
    • Slow/verbose — agent was too thorough where speed was needed (→ note preference)
    • User changed mind — not an agent issue, just context
手动中断（用户按下Ctrl+C，说出“stop”、“wait”、“no”，中途重定向）是高信号事件。这意味着Agent在做用户不希望的事情。对于每个发现的中断：
  1. Agent当时在做什么？ — 被中断的操作
  2. 用户为什么中断？ — 方向错误、速度太慢、不必要的工作、方法错误、范围蔓延
  3. 中断后发生了什么？ — 用户是否重定向到其他方法？是否放弃任务？
  4. 根本原因 — 归类为以下之一：
    • 知识缺失 — Agent不知道它应该知道的内容（→ 添加到共享上下文或预设）
    • 错误默认值 — Agent选择了听起来合理但不正确的方法（→ 添加预设或skill指导）
    • 范围蔓延 — Agent的工作超出了要求范围（→ 记录为过度设计模式）
    • 工具误用 — Agent使用了错误的工具或方法（→ 更新skill或添加到预设）
    • 缓慢/冗长 — Agent在需要速度的地方过于繁琐（→ 记录偏好）
    • 用户改变主意 — 不是Agent的问题，只是上下文变化

Step 4b: User Suggestion Analysis

步骤4b：用户建议分析

When the user provides mid-session suggestions ("try X instead", "use Y", "you should Z", "what about..."), these are course corrections that reveal knowledge gaps. For each suggestion found:
  1. What did the user suggest? — the specific guidance
  2. Was this a correction or an enhancement? — fixing wrong direction vs. adding info the agent couldn't know
  3. Is this generalizable? — would this help in future similar tasks?
  4. Where should it live? — classify as:
    • Preset — a convention to always follow (→ CLAUDE.md Presets)
    • Shared knowledge — domain info for the project (→ 
      shared/<topic>.md
      )
    • Skill update — procedural improvement (→ update relevant skill)
    • One-off — specific to this task, not generalizable
当用户在会话中提供建议（“试试X”、“使用Y”、“你应该Z”、“要不要...”）时，这些是修正方向的提示，揭示了知识缺口。对于每个发现的建议：
  1. 用户建议了什么？ — 具体指导内容
  2. 这是修正还是增强？ — 纠正错误方向 vs 添加Agent无法知晓的信息
  3. 是否可推广？ — 这对未来类似任务有帮助吗？
  4. 应存放何处？ — 归类为：
    • 预设 — 应始终遵循的约定（→ CLAUDE.md Presets）
    • 共享知识 — 项目领域信息（→ 
      shared/<topic>.md
      ）
    • Skill更新 — 流程改进（→ 更新相关skill）
    • 一次性内容 — 仅适用于此任务，不可推广

Step 4c: Session Efficiency Analysis

步骤4c：会话效率分析

Examine how work was done, not just what was learned. For each bead's session:
  1. Tool usage patterns:
    • Over-reliance on Bash vs dedicated tools (Read/Grep/Glob when cat/grep/find were used)
    • Missed skill invocations — manual steps that a skill already automates
    • Repeated tool failures — same tool called multiple times with wrong args or approach
  2. Friction indicators:
    • Long back-and-forth clarifications before work started
    • Repeated retries of the same action (e.g., retry loop on a failing command)
    • Context switches mid-task (started one approach, abandoned, tried another)
  3. Quantitative signals (approximate counts):
    • Interruptions per bead (from Step 4a)
    • Tool failure rate (failed tool calls / total tool calls)
    • Clarification rounds before productive work began
检查工作完成的方式，而不仅仅是学到的内容。对于每个bead的会话：
  1. 工具使用模式：
    • 过度依赖Bash而非专用工具（使用cat/grep/find时却用了Read/Grep/Glob）
    • 遗漏skill调用 — 手动执行了已有skill可自动化的步骤
    • 重复工具失败 — 同一工具因错误参数或方法被多次调用失败
  2. 摩擦指标：
    • 工作开始前长时间来回澄清
    • 重复重试同一操作（例如，对失败的命令进行重试循环）
    • 任务中途切换上下文（开始一种方法，放弃，尝试另一种）
  3. 量化信号（近似计数）：
    • 每个bead的中断次数（来自步骤4a）
    • 工具失败率（失败的工具调用数 / 总工具调用数）
    • 进入高效工作前的澄清轮次

Step 5: Per Bead — Write to Shared

步骤5：逐个Bead — 写入共享目录

Distill findings to 
projects/<project>/shared/<topic>.md
:
  • If the file exists, append a new section referencing the bead
  • If new, create with a clear heading and bead reference
  • Format: concise bullets, not prose
  • Include bead ID as provenance: 
    (from <bead-id>)
  • If nothing worth distilling, skip this step and note why
将提炼结果写入
projects/<project>/shared/<topic>.md
：
  • 如果文件已存在，添加引用该bead的新章节
  • 如果是新文件，创建清晰的标题并引用bead
  • 格式：简洁的项目符号，而非散文
  • 包含bead ID作为来源：
    (from <bead-id>)
  • 如果没有值得提炼的内容，跳过此步骤并记录原因

Step 6: Workflow Improvements

步骤6：工作流改进

Review the work session for improvements to the workspace system itself. Two categories:
回顾工作会话，以改进工作区系统本身。分为两类：

6a: Compliance Gaps — configured workflows not followed

6a：合规缺口 — 未遵循已配置的工作流

Compare what happened in the session against what's configured in:
  • CLAUDE.md (root + project) — presets, conventions, workflow steps
  • Shared context (
    projects/<project>/shared/
    ) — known patterns, decisions
  • Skills — established procedures that were skipped or done ad-hoc
For each gap found, determine:
  • Was the workflow unclear, outdated, or wrong? → Propose an update to the source
  • Was it simply missed? → Note it as a reminder (no system change needed)
将会话中实际发生的情况与以下配置内容进行对比：
  • CLAUDE.md（根目录 + 项目）— 预设、约定、工作流步骤
  • 共享上下文 (
    projects/<project>/shared/
    ) — 已知模式、决策
  • Skills — 已建立但被跳过或临时执行的流程
对于每个发现的缺口，确定：
  • 工作流是否不清晰、过时或错误？→ 提议更新来源
  • 只是被遗漏了？→ 记录为提醒（无需更改系统）

6b: New Knowledge Opportunities — patterns to codify

6b：新知识机会 — 需编纂的模式

Look for repetitive work that could be accelerated:
  • Recurring patterns — same sequence of steps done multiple times → candidate for a new skill or shared knowledge
  • Manual lookups — information repeatedly searched for → add to shared context or CLAUDE.md
  • Boilerplate — repeated code/config/commands → candidate for a template or script
  • Implicit conventions — decisions made consistently but not written down → candidate for presets
  • Tool misuse patterns — same wrong tool choice across beads (e.g., Bash grep instead of Grep tool, cat instead of Read) → candidate for preset or feedback memory
  • Missed skill invocations — manual multi-step sequences that an existing skill already automates → reminder or skill discoverability improvement
寻找可加速的重复性工作：
  • 重复模式 — 多次执行相同步骤序列 → 新skill或共享知识的候选
  • 手动查找 — 反复搜索的信息 → 添加到共享上下文或CLAUDE.md
  • 模板化内容 — 重复的代码/配置/命令 → 模板或脚本的候选
  • 隐含约定 — 一致做出但未书面记录的决策 → 预设的候选
  • 工具误用模式 — 多个bead中出现相同的错误工具选择（例如，使用Bash grep而非Grep工具，使用cat而非Read）→ 预设或反馈记忆的候选
  • 遗漏skill调用 — 手动执行多步骤序列，而已有skill可自动化 → 提醒或skill可发现性改进

6c: Interruption & Suggestion Patterns

6c：中断与建议模式

Roll up findings from Step 4a and 4b across all beads being distilled. Look for:
  • Repeated interruption root causes — same type of mistake across beads → systemic issue
  • Cluster of similar suggestions — user keeps teaching the same thing → must be codified
  • Project-specific vs. global — does the fix belong in project CLAUDE.md or root CLAUDE.md?
  • Friction hotspots — recurring slow/painful sequences across beads (e.g., same setup steps repeatedly failing)
  • Tool failure clusters — same tool failing the same way repeatedly → systemic config or knowledge issue
汇总步骤4a和4b中所有正在提炼的bead的结果。寻找：
  • 重复的中断根本原因 — 多个bead中出现相同类型的错误 → 系统性问题
  • 相似建议集群 — 用户反复教授同一内容 → 必须编纂
  • 项目特定 vs 全局 — 修复应放在项目CLAUDE.md还是根目录CLAUDE.md？
  • 摩擦热点 — 多个bead中重复出现的缓慢/痛苦序列（例如，相同的设置步骤反复失败）
  • 工具失败集群 — 同一工具以相同方式反复失败 → 系统性配置或知识问题

Output

输出

Present findings to the user as a table:
| # | Category    | Finding | Proposed Action |
|---|-------------|---------|-----------------|
| 1 | gap         | Didn't use worktree for code changes | Reminder (workflow exists) |
| 2 | gap         | Preset X is outdated | Update CLAUDE.md |
| 3 | pattern     | Repeated Meegle field updates | New skill or script |
| 4 | pattern     | Always look up same roster info | Add to shared context |
| 5 | interruption| Agent over-researched before acting | Add preset: "bias toward action for simple tasks" |
| 6 | suggestion  | User taught API pagination pattern 3x | Add to shared/api-patterns.md |
Ask the user which actions to apply. Execute confirmed actions (edit CLAUDE.md, create shared docs, file new beads for larger improvements).
将结果以表格形式呈现给用户：
| # | Category    | Finding | Proposed Action |
|---|-------------|---------|-----------------|
| 1 | gap         | Didn't use worktree for code changes | Reminder (workflow exists) |
| 2 | gap         | Preset X is outdated | Update CLAUDE.md |
| 3 | pattern     | Repeated Meegle field updates | New skill or script |
| 4 | pattern     | Always look up same roster info | Add to shared context |
| 5 | interruption| Agent over-researched before acting | Add preset: "bias toward action for simple tasks" |
| 6 | suggestion  | User taught API pagination pattern 3x | Add to shared/api-patterns.md |
询问用户要应用哪些操作。执行确认的操作（编辑CLAUDE.md、创建共享文档、为较大改进创建新bead）。

Step 7: Preset Candidates

步骤7：预设候选

If any preset candidates were identified in Step 4 or Step 6:
  • Show them to the user
  • Ask if they should be added to CLAUDE.md Presets section
  • Apply if confirmed
如果在步骤4或步骤6中识别出任何预设候选：
  • 展示给用户
  • 询问是否应添加到CLAUDE.md的Presets部分
  • 若确认则应用

Step 8: Mark Distilled

步骤8：标记为已提炼

bash
bd label add <id> distilled
bash
bd label add <id> distilled

Step 9: Archive Context

步骤9：归档上下文

If a context directory exists at 
projects/<project>/contexts/<bead-id>/
:
bash
git mv projects/<project>/contexts/<bead-id> projects/<project>/contexts/archived/<bead-id>
If no context directory exists, skip this step.
如果上下文目录
projects/<project>/contexts/<bead-id>/
存在：
bash
git mv projects/<project>/contexts/<bead-id> projects/<project>/contexts/archived/<bead-id>
如果没有上下文目录，跳过此步骤。

Step 10: Commit

步骤10：提交

bash
git add projects/<project>/shared/
git add projects/<project>/contexts/
bd sync
git commit -m "chore: distill and archive <bead-id(s)>"
bash
git add projects/<project>/shared/
git add projects/<project>/contexts/
bd sync
git commit -m "chore: distill and archive <bead-id(s)>"

Step 11: Summary

步骤11：总结

Distilled:
- <bead-id>: <title> → shared/<topic>.md
- <bead-id>: <title> → (nothing to distill, archived only)
Interruptions analyzed: <count> found, root causes: <list top causes>
User suggestions extracted: <count> found, <count> generalizable
Workflow improvements: <count> gaps found, <count> patterns identified, <count> actions applied
Session efficiency: <count> friction points, <count> tool misuse patterns, <count> missed skill invocations
Preset candidates: <count> proposed, <count> applied
Archived: <count> context dirs moved
提炼情况：
- <bead-id>: <标题> → shared/<topic>.md
- <bead-id>: <标题> → （无内容可提炼，仅归档）
分析的中断次数：发现<count>次，根本原因：<列出主要原因>
提取的用户建议：发现<count>次，<count>次可推广
工作流改进：发现<count>个缺口，识别<count>种模式，应用<count>项操作
会话效率：<count>个摩擦点，<count>种工具误用模式，<count>次遗漏skill调用
预设候选：提议<count>个，应用<count>个
归档情况：<count>个上下文目录已移动

Tips

提示

  • Batch multiple beads in one run for efficiency
  • Not every bead produces distillable knowledge — quick fixes and chores often don't
  • Focus on "what would help the next person (or future session) doing similar work?"
  • The 
    distilled
    label prevents re-processing — don't skip it even if nothing was distilled
  • Use 
    bd query "status=closed AND label=distilled" -a
    to review past distillations
  • 一次批量处理多个bead以提高效率
  • 并非每个bead都能产生可提炼的知识 — 快速修复和杂务通常没有
  • 聚焦于“什么能帮助下一个人（或未来会话）完成类似工作？”
  • distilled
    标签可防止重复处理 — 即使没有提炼出内容也不要跳过此步骤
  • 使用
    bd query "status=closed AND label=distilled" -a
    查看过往提炼记录