Back to Details

trace

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Trace Skill

Trace Skill

Quick Ref: Trace design decisions through CASS sessions, handoffs, git, and artifacts. Output: 
.agents/research/YYYY-MM-DD-trace-*.md
YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.
快速参考： 通过CASS会话、工作交接记录、Git和工件追踪设计决策。输出文件：
.agents/research/YYYY-MM-DD-trace-*.md
你必须执行此工作流程，不能仅进行描述。

When to Use

适用场景

  • Trace HOW architectural decisions evolved
  • Find WHEN a concept was introduced
  • Understand WHY something was designed a certain way
  • Build provenance chain for design decisions
For knowledge artifact lineage (learnings, patterns, tiers), use 
/provenance
instead.
CLI dependencies: cass (session search). If cass is unavailable, skip transcript search and rely on git log, handoff docs, and 
.agents/
artifacts for decision tracing.
  • 追踪架构决策的演变过程
  • 查找概念的引入时间
  • 理解某项设计的原因
  • 为设计决策构建溯源链
若需追踪知识工件的溯源（经验、模式、层级），请使用
/provenance
。
CLI依赖： cass（会话搜索工具）。若cass不可用，则跳过会话记录搜索，仅依赖Git日志、交接文档和
.agents/
目录下的工件进行决策追踪。

Execution Steps

执行步骤

Given 
/trace <concept>
:
当输入
/trace <concept>
时：

Step 1: Classify Target Type

步骤1：分类目标类型

Determine what kind of provenance to trace:
IF target is a file path (contains "/" or "."):
  → Use /provenance (artifact lineage)

IF target is a git ref (sha, branch, tag):
  → Use git-based tracing (Step 2b)

ELSE (keyword/concept):
  → Use design decision tracing (Step 2a)
确定需要追踪的溯源类型：
如果目标是文件路径（包含 "/" 或 "."）:
  → 使用 /provenance（工件溯源）

如果目标是Git引用（哈希值、分支、标签）:
  → 使用基于Git的追踪（步骤2b）

其他情况（关键词/概念）:
  → 使用设计决策追踪（步骤2a）

Step 2a: Design Decision Tracing (Concepts)

步骤2a：设计决策追踪（针对概念）

Launch parallel search agents using Task tool:
Tool: Task
Parameters:
  subagent_type: "Explore"
  model: "haiku"
  description: "CASS search: <concept>"
  prompt: |
    Search session transcripts for: <concept>

    Run this command:
    cass search "<concept>" --json --limit 10

    Parse the JSON output and extract:
    - Session dates (created_at field, convert from Unix ms)
    - Session paths (source_path field)
    - Agents used (agent field)
    - Relevance scores (score field)
    - Key snippets (snippet/content fields)

    Return a structured list sorted by date (oldest first).
Tool: Task
Parameters:
  subagent_type: "Explore"
  model: "haiku"
  description: "Handoff search: <concept>"
  prompt: |
    Search handoff documents for: <concept>

    1. List handoff files:
       ls -la .agents/handoff/*.md 2>/dev/null

    2. Search for concept mentions:
       grep -l "<concept>" .agents/handoff/*.md 2>/dev/null

    3. For each matching file, extract:
       - File date (from filename YYYY-MM-DD)
       - Context around the mention (grep -B5 -A5)
       - Related decisions or questions

    Return a structured list sorted by date.
Tool: Task
Parameters:
  subagent_type: "Explore"
  model: "haiku"
  description: "Git search: <concept>"
  prompt: |
    Search git history for: <concept>

    1. Search commit messages:
       git log --oneline --grep="<concept>" | head -20

    2. For interesting commits, get details:
       git show --stat <commit-sha>

    3. Extract:
       - Commit dates
       - Commit messages
       - Files changed
       - Authors

    Return a structured list sorted by date.
Tool: Task
Parameters:
  subagent_type: "Explore"
  model: "haiku"
  description: "Research search: <concept>"
  prompt: |
    Search research and learning artifacts for: <concept>

    1. Search research docs:
       grep -l "<concept>" .agents/research/*.md 2>/dev/null

    2. Search learnings:
       grep -l "<concept>" .agents/learnings/*.md 2>/dev/null

    3. Search patterns:
       grep -l "<concept>" .agents/patterns/*.md 2>/dev/null

    4. For each match, extract:
       - File date (from filename or modification time)
       - Context around the mention
       - Related concepts

    Return a structured list sorted by date.
Wait for all 4 agents to complete.
使用Task工具启动并行搜索Agent：
工具: Task
参数:
  subagent_type: "Explore"
  model: "haiku"
  description: "CASS搜索: <concept>"
  prompt: |
    在会话记录中搜索：<concept>

    执行以下命令:
    cass search "<concept>" --json --limit 10

    解析JSON输出并提取:
    - 会话日期（created_at字段，从Unix毫秒时间戳转换）
    - 会话路径（source_path字段）
    - 使用的Agent（agent字段）
    - 相关性得分（score字段）
    - 关键片段（snippet/content字段）

    返回按日期排序（从旧到新）的结构化列表。
工具: Task
参数:
  subagent_type: "Explore"
  model: "haiku"
  description: "交接文档搜索: <concept>"
  prompt: |
    在交接文档中搜索：<concept>

    1. 列出交接文件:
       ls -la .agents/handoff/*.md 2>/dev/null

    2. 搜索包含该概念的文件:
       grep -l "<concept>" .agents/handoff/*.md 2>/dev/null

    3. 对每个匹配的文件，提取:
       - 文件日期（从文件名的YYYY-MM-DD获取）
       - 提及该概念的上下文（grep -B5 -A5）
       - 相关决策或问题

    返回按日期排序的结构化列表。
工具: Task
参数:
  subagent_type: "Explore"
  model: "haiku"
  description: "Git搜索: <concept>"
  prompt: |
    在Git历史中搜索：<concept>

    1. 搜索提交信息:
       git log --oneline --grep="<concept>" | head -20

    2. 对重要的提交，获取详细信息:
       git show --stat <commit-sha>

    3. 提取:
       - 提交日期
       - 提交信息
       - 修改的文件
       - 提交作者

    返回按日期排序的结构化列表。
工具: Task
参数:
  subagent_type: "Explore"
  model: "haiku"
  description: "研究文档搜索: <concept>"
  prompt: |
    在研究和学习工件中搜索：<concept>

    1. 搜索研究文档:
       grep -l "<concept>" .agents/research/*.md 2>/dev/null

    2. 搜索经验总结:
       grep -l "<concept>" .agents/learnings/*.md 2>/dev/null

    3. 搜索模式文档:
       grep -l "<concept>" .agents/patterns/*.md 2>/dev/null

    4. 对每个匹配的文件，提取:
       - 文件日期（从文件名或修改时间获取）
       - 提及该概念的上下文
       - 相关概念

    返回按日期排序的结构化列表。
等待所有4个Agent完成搜索。

Step 2b: Git-Based Tracing (Commits/Refs)

步骤2b：基于Git的追踪（针对提交/引用）

For git refs, trace the commit history:
bash
undefined
对于Git引用，追踪提交历史：
bash
undefined

Get commit details

获取提交详情

git show --stat <ref>
git show --stat <ref>

Get commit ancestry

获取提交祖先链

git log --oneline --ancestry-path <ref>..HEAD | head -20
git log --oneline --ancestry-path <ref>..HEAD | head -20

Find related commits

查找相关提交

git log --oneline --all --grep="$(git log -1 --format=%s <ref> | head -c 50)" | head -10
undefined
git log --oneline --all --grep="$(git log -1 --format=%s <ref> | head -c 50)" | head -10
undefined

Step 3: Build Timeline

步骤3：构建时间线

Merge results from all sources into a single timeline:
markdown
| Date | Source | Event | Evidence |
|------|--------|-------|----------|
| YYYY-MM-DD | CASS | First mention in session | session-id, snippet |
| YYYY-MM-DD | Handoff | Decision recorded | handoff-file, context |
| YYYY-MM-DD | Git | Implementation committed | commit-sha, message |
| YYYY-MM-DD | Research | Documented in research | research-file |
Deduplication rules:
  • Same content within 24 hours = single event (note multiple sources)
  • Same session ID = single event
  • Preserve ALL sources as evidence
Sorting:
  • Chronological order (oldest first)
  • Show evolution of the concept over time
将所有来源的结果合并为单一时间线：
markdown
| 日期 | 来源 | 事件 | 证据 |
|------|--------|-------|----------|
| YYYY-MM-DD | CASS | 首次在会话中提及 | 会话ID、片段 |
| YYYY-MM-DD | 交接文档 | 记录决策 | 交接文件、上下文 |
| YYYY-MM-DD | Git | 提交实现 | 提交哈希、信息 |
| YYYY-MM-DD | 研究文档 | 记录在研究文档中 | 研究文件 |
去重规则：
  • 24小时内的相同内容 = 单个事件（注明多个来源）
  • 相同会话ID = 单个事件
  • 保留所有来源作为证据
排序规则：
  • 按时间顺序（从旧到新）
  • 展示概念随时间的演变过程

Step 4: Extract Key Decisions

步骤4：提取关键决策

For each event in timeline, identify:
  • What changed: The decision or evolution
  • Why: Reasoning if available
  • Who: Session/author/commit author
  • Evidence: Link to source (session path, file, commit)
针对时间线中的每个事件，识别：
  • 变更内容： 决策或演变点
  • 原因： 若有则记录推理过程
  • 相关人员： 会话参与者/作者/提交作者
  • 证据： 来源链接（会话路径、文件、提交）

Step 5: Write Trace Report

步骤5：撰写追踪报告

Write to: 
.agents/research/YYYY-MM-DD-trace-<concept-slug>.md
markdown
undefined
写入路径： 
.agents/research/YYYY-MM-DD-trace-<concept-slug>.md
markdown
undefined

Trace: <Concept>

追踪报告：<概念>

Date: YYYY-MM-DD Query: <original concept> Sources searched: CASS, Handoffs, Git, Research
日期： YYYY-MM-DD 查询词： <原始概念> 搜索来源： CASS、交接文档、Git、研究文档

Summary

摘要

<2-3 sentence overview of how the concept evolved>
<2-3句话概述概念的演变过程>

Timeline

时间线

DateSourceEventEvidence
............
日期来源事件证据
............

Key Decisions

关键决策

Decision 1: <title>

决策1：<标题>

  • Date: YYYY-MM-DD
  • Source: <CASS session / Handoff / Git commit>
  • What: <what was decided>
  • Why: <reasoning if known>
  • Evidence: <link/path>
  • 日期： YYYY-MM-DD
  • 来源： <CASS会话 / 交接文档 / Git提交>
  • 内容： 做出的决策
  • 原因： 已知的推理过程
  • 证据： <链接/路径>

Decision 2: <title>

决策2：<标题>

...
...

Evolution Summary

演变总结

<How the concept changed over time, key inflection points>
<概念随时间的变化情况、关键转折点>

Current State

当前状态

<Where the concept stands now based on most recent evidence>
<基于最新证据的概念现状>

Related Concepts

相关概念

  • <related concept 1> - see 
    /trace <concept1>
  • <related concept 2> - see 
    /trace <concept2>
  • <相关概念1> - 查看 
    /trace <concept1>
  • <相关概念2> - 查看 
    /trace <concept2>

Sources

来源详情

CASS Sessions

CASS会话

DateSession PathScore
.........
日期会话路径得分
.........

Handoff Documents

交接文档

DateFileContext
.........
日期文件上下文
.........

Git Commits

Git提交

DateSHAMessage
.........
日期哈希值提交信息
.........

Research/Learnings

研究/经验总结

DateFile
......
undefined
日期文件
......
undefined

Step 6: Report to User

步骤6：向用户反馈

Tell the user:
  1. Concept traced successfully
  2. Timeline of evolution (key dates)
  3. Most significant decisions
  4. Location of trace report
  5. Related concepts to explore
告知用户：
  1. 概念追踪完成
  2. 演变时间线（关键日期）
  3. 最重要的决策
  4. 追踪报告的位置
  5. 可探索的相关概念

Handling Edge Cases

边缘情况处理

No CASS Results

无CASS结果

IF cass search returns 0 results:
  - Log: "No session transcripts mention '<concept>'"
  - Continue with other sources
  - Note in report: "Concept not found in session history"
如果cass搜索返回0条结果:
  - 记录："会话记录中未提及'<concept>'"
  - 继续使用其他来源
  - 在报告中注明："会话历史中未找到该概念"

No Handoff Documents

无交接文档

IF .agents/handoff/ doesn't exist OR no matches:
  - Log: "No handoff documents mention '<concept>'"
  - Continue with other sources
  - Note in report: "Concept not documented in handoffs"
如果.agents/handoff/目录不存在或无匹配结果:
  - 记录："交接文档中未提及'<concept>'"
  - 继续使用其他来源
  - 在报告中注明："交接文档中未记录该概念"

Ambiguous Concept (Too Many Results)

概念模糊（结果过多）

IF CASS returns >20 results:
  - Show top 10 by score
  - Ask user: "Many sessions mention this. Want to narrow by date range or workspace?"
  - Suggest related but more specific concepts
如果CASS返回超过20条结果:
  - 展示得分前10的结果
  - 询问用户："多个会话提及该概念，是否需要按日期范围或工作区缩小范围？"
  - 建议相关但更具体的概念

All Sources Empty

所有来源无结果

IF all 4 searches return nothing:
  - Report: "No provenance found for '<concept>'"
  - Suggest: "Try related terms: <suggestions>"
  - Ask: "Is this concept documented somewhere else?"
如果4种搜索均无结果:
  - 反馈："未找到'<concept>'的溯源信息"
  - 建议："尝试相关术语：<建议词>"
  - 询问："该概念是否记录在其他位置？"

Key Rules

核心规则

  • Search ALL sources - CASS, handoffs, git, research
  • Build timeline - chronological evolution is the goal
  • Cite evidence - every claim needs a source
  • Handle gaps gracefully - not all concepts are in all sources
  • Write report - trace must produce 
    .agents/research/
    artifact
  • 搜索所有来源 - CASS、交接文档、Git、研究文档
  • 构建时间线 - 目标是展示按时间顺序的演变过程
  • 引用证据 - 每个结论都需要来源支持
  • 优雅处理空白 - 并非所有概念都存在于所有来源中
  • 撰写报告 - 追踪必须生成
    .agents/research/
    目录下的工件

Relationship to /provenance

与/provenance的关系

SkillPurposeInputOutput
/provenance
Artifact lineageFile pathTier/promotion history
/trace
Design decisionsConcept/keywordTimeline of evolution
Use 
/provenance
for: "Where did this learning come from?" Use 
/trace
for: "How did we decide on this architecture?"
Skill用途输入输出
/provenance
工件溯源文件路径层级/推广历史
/trace
设计决策追踪概念/关键词演变时间线
使用
/provenance
解决："这条经验来自哪里？" 使用
/trace
解决："我们是如何确定这个架构的？"

Examples

示例

bash
undefined
bash
undefined

Trace a design decision

追踪设计决策

/trace "three-level architecture"
/trace "三级架构"

Trace a role/concept

追踪角色/概念

/trace "Chiron"
/trace "Chiron"

Trace a pattern

追踪模式

/trace "brownian ratchet"
/trace "布朗棘轮"

Trace a feature

追踪功能

/trace "parallel wave execution"
undefined
/trace "并行波执行"
undefined