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 $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 spawn_agent or codex exec for parallel exploration. See ../shared/SKILL.md ("Backend Detection") 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

# 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 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." |

Local Resources

references/

• [references/discovery-patterns.md](references/discovery-patterns.md)
• [references/edge-cases.md](references/edge-cases.md)
• [references/report-template.md](references/report-template.md)

scripts/

• scripts/validate.sh