trace

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