痕迹
- 作者仓库星标 39
- 作者仓库 awesome-omni-skill
- 领域
- 工程开发
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @diegosouzapw · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# Trace a design decision
/trace "three-level architecture"
# Trace a role/concept
/trace "Chiron"
# Trace a pattern
/trace "brownian ratchet"
# Trace a feature
/trace "parallel wave execution"
第 1 步:对目标类型进行分类
确定要追踪的来源类型:
步骤 2a:设计决策追踪(概念)
启动 4 个并行搜索代理(CASS、Handoff、Git、Research)并等待全部完成。后端:代理使用`Task(subagent_type="Explore")`,它映射到OpenCode中的`task(subagent_type="explore")`。有关共享合约,请参阅`skills/shared/SKILL.md`(“运行时本机生成后端选择”)。阅读`references/discovery-patterns.md` 了解代理定义和提示。
步骤 2b:基于 Git 的跟踪(提交/引用)
阅读`references/discovery-patterns.md`了解基于 git 的跟踪命令。
第 3 步:制定时间表
将所有来源的结果合并到一个按时间顺序排列的时间线中(最早的在前)。消除同一天/同一会话事件的重复数据。每个主张都需要引用来源。
第 4 步:提取关键决策
对于时间线中的每个事件,确定: 发生了什么变化:决策或演变 原因:推理(如果有) 谁:会话/作者/提交作者 证据:源链接(会话路径、文件、提交)
第5步:编写跟踪报告
写入:`.agents/research/YYYY-MM-DD-trace-<concept-slug>.md` 阅读`references/report-template.md`,了解完整的报告格式和重复数据删除规则。
第 6 步:向用户报告
告诉用户: 成功追踪概念 演变时间线(关键日期) 最重要的决策 追踪报告的位置
# 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.**
## 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.
## Execution Steps
Given `/trace <concept>`:
### Step 1: Classify Target Type
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)
```
### Step 2a: Design Decision Tracing (Concepts)
Launch 4 parallel search agents (CASS, Handoff, Git, Research) and wait for all to complete.
**Backend:** Agents use `Task(subagent_type="Explore")` which maps to `task(subagent_type="explore")` in OpenCode. See `skills/shared/SKILL.md` ("Runtime-Native Spawn Backend Selection") for the shared contract.
Read `references/discovery-patterns.md` for agent definitions and prompts.
### Step 2b: Git-Based Tracing (Commits/Refs)
Read `references/discovery-patterns.md` for git-based tracing commands.
### Step 3: Build Timeline
Merge results from all sources into a single chronological timeline (oldest first). Deduplicate same-day/same-session events. Every claim needs a source citation.
### Step 4: Extract Key Decisions
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
**Write to:** `.agents/research/YYYY-MM-DD-trace-<concept-slug>.md`
Read `references/report-template.md` for the full report format and deduplication rules.
### Step 6: Report to User
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
## Handling Edge Cases
Read `references/edge-cases.md` for handling: no CASS results, no handoffs, ambiguous concepts (>20 results), and all-sources-empty scenarios. General principle: continue with remaining sources and note gaps in the report.
## 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
## Relationship to /provenance
| Skill | Purpose | Input | Output |
|-------|---------|-------|--------|
| `/provenance` | Artifact lineage | File path | Tier/promotion history |
| `/trace` | Design decisions | Concept/keyword | Timeline of evolution |
Use `/provenance` for: "Where did this learning come from?"
Use `/trace` for: "How did we decide on this architecture?"
## Examples
```bash
# Trace a design decision
/trace "three-level architecture"
# Trace a role/concept
/trace "Chiron"
# Trace a pattern
/trace "brownian ratchet"
# Trace a feature
/trace "parallel wave execution"
```
### Tracing an Architectural Decision
**User says:** `/trace "agent team protocol"`
**What happens:**
1. Agent classifies target as concept (not file path or git ref)
2. Agent launches 4 parallel agents: CASS search, handoff search, git log search, research artifact search
3. CASS finds 8 sessions mentioning "agent team", handoff finds 2 docs, git finds 3 commits, research finds 1 analysis
4. Agent builds chronological timeline from 2026-01-15 (first mention) to 2026-02-08 (latest update)
5. Agent extracts 5 key decisions: initial SendMessage design, TeamCreate addition, deliberation protocol, in-process mode, delegate mode
6. Agent writes trace report to `.agents/research/2026-02-13-trace-agent-team-protocol.md` with full timeline and citations
**Result:** Complete evolution timeline showing how agent team protocol developed across 7 sessions with source citations.
### Tracing from Git Commit
**User says:** `/trace abc1234`
**What happens:**
1. Agent detects git ref format (short sha)
2. Agent runs git-based tracing commands to get commit details, changed files, related commits
3. Agent uses `git log --grep` to find related work
4. Agent searches `.agents/` for contemporary research/plans
5. Agent builds timeline focused on that specific change
6. Agent writes report showing commit context, what changed, why (from commit message and related docs)
**Result:** Trace report links commit to broader design context from surrounding artifacts.
## Troubleshooting
| Problem | Cause | Solution |
|---------|-------|----------|
| CASS returns no results | Session search not installed or query too specific | Check `which cass`. If missing, skip CASS and rely on handoffs/git/research. Try broader query terms. |
| Timeline has gaps | Not all decisions documented in searchable artifacts | Note gaps in report. Suggest interviewing team members or checking Slack/email archives for missing context. |
| Too many results (>50 matches) | Very broad concept or high-frequency term | Read `references/edge-cases.md` for ambiguous concept handling. Narrow query or filter by date range. Ask user for more specific aspect to trace. |
| Empty trace report (all sources failed) | Concept genuinely undocumented or typo | Verify spelling. Try synonyms. Report to user: "No documented history found. This may be a new concept or may need different search terms." |
章节与文件索引
按说明文件中的顺序排列。
何时使用
执行步骤
第 1 步:对目标类型进行分类
步骤 2a:设计决策追踪(概念)
步骤 2b:基于 Git 的跟踪(提交/引用)
文件/命令 -> .agents/research/YYYY-MM-DD-trace-*.md · /provenance · .agents/ · /trace <concept> · Task(subagent_type="Explore") · task(subagent_type="explore") · skills/shared/SKILL.md · references/discovery-patterns.md
内容校验值 -> c0bec0399ff5
当前原文的自动摘译,尚未人工审校。
何时使用
追踪架构决策是如何演变的 查找概念何时被引入 了解为什么以某种方式设计某些东西 为设计决策构建起源链 对于知识工件谱系(学习、模式、层),请改用
/provenance。执行步骤
给定
/trace <concept>: