trace

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 $curate --mode=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 `$curate --mode=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 Artifact Provenance

Use $curate --mode=provenance for: "Where did this learning come from?" Use /trace for: "How did we decide on this architecture?"

Examples

# 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

Reference Documents

• references/trace.feature — Executable spec: target-type routing, parallel multi-source search, cited chronological timeline, key-decision extraction, report + graceful gaps (soc-qk4b)
• references/discovery-patterns.md — Search-agent definitions and git-based tracing commands
• references/report-template.md — Trace report format and deduplication rules
• references/edge-cases.md — Empty/ambiguous source handling