| name | trace |
| description | Trace decisions through artifacts. |
| practices | ["distributed-tracing","adr","ebpf-observability"] |
| hexagonal_role | supporting |
| consumes | [] |
| produces | ["result.json"] |
| context_rel | [{"kind":"customer-of","with":"provenance"}] |
| skill_api_version | 1 |
| allowed-tools | Read, Grep, Glob, Bash |
| context | {"window":"fork","intent":{"mode":"task"},"sections":{"exclude":["HISTORY"]},"intel_scope":"full"} |
| metadata | {"tier":"knowledge","dependencies":["provenance"]} |
| output_contract | stdout: decision provenance chain |
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