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)

Tool: Task
Parameters:
  subagent_type: "Explore"
  model: "haiku"
  description: "CASS search: <concept>"
  prompt: |
    Search session transcripts for: <concept>

    Run this command:
    cass search "<concept>" --json --limit 10

    Parse the JSON output and extract:
    - Session dates (created_at field, convert from Unix ms)
    - Session paths (source_path field)
    - Agents used (agent field)
    - Relevance scores (score field)
    - Key snippets (snippet/content fields)

    Return a structured list sorted by date (oldest first).

Tool: Task
Parameters:
  subagent_type: "Explore"
  model: "haiku"
  description: "Handoff search: <concept>"
  prompt: |
    Search handoff documents for: <concept>

    1. List handoff files:
       ls -la .agents/handoff/*.md 2>/dev/null

    2. Search for concept mentions:
       grep -l "<concept>" .agents/handoff/*.md 2>/dev/null

    3. For each matching file, extract:
       - File date (from filename YYYY-MM-DD)
       - Context around the mention (grep -B5 -A5)
       - Related decisions or questions

    Return a structured list sorted by date.

Tool: Task
Parameters:
  subagent_type: "Explore"
  model: "haiku"
  description: "Git search: <concept>"
  prompt: |
    Search git history for: <concept>

    1. Search commit messages:
       git log --oneline --grep="<concept>" | head -20

    2. For interesting commits, get details:
       git show --stat <commit-sha>

    3. Extract:
       - Commit dates
       - Commit messages
       - Files changed
       - Authors

    Return a structured list sorted by date.

Tool: Task
Parameters:
  subagent_type: "Explore"
  model: "haiku"
  description: "Research search: <concept>"
  prompt: |
    Search research and learning artifacts for: <concept>

    1. Search research docs:
       grep -l "<concept>" .agents/research/*.md 2>/dev/null

    2. Search learnings:
       grep -l "<concept>" .agents/learnings/*.md 2>/dev/null

    3. Search patterns:
       grep -l "<concept>" .agents/patterns/*.md 2>/dev/null

    4. For each match, extract:
       - File date (from filename or modification time)
       - Context around the mention
       - Related concepts

    Return a structured list sorted by date.

# Get commit details
git show --stat <ref>

# Get commit ancestry
git log --oneline --ancestry-path <ref>..HEAD | head -20

# Find related commits
git log --oneline --all --grep="$(git log -1 --format=%s <ref> | head -c 50)" | head -10

| Date | Source | Event | Evidence |
|------|--------|-------|----------|
| YYYY-MM-DD | CASS | First mention in session | session-id, snippet |
| YYYY-MM-DD | Handoff | Decision recorded | handoff-file, context |
| YYYY-MM-DD | Git | Implementation committed | commit-sha, message |
| YYYY-MM-DD | Research | Documented in research | research-file |

# Trace: <Concept>

**Date:** YYYY-MM-DD
**Query:** <original concept>
**Sources searched:** CASS, Handoffs, Git, Research

## Summary

<2-3 sentence overview of how the concept evolved>

## Timeline

| Date | Source | Event | Evidence |
|------|--------|-------|----------|
| ... | ... | ... | ... |

## Key Decisions

### Decision 1: <title>
- **Date:** YYYY-MM-DD
- **Source:** <CASS session / Handoff / Git commit>
- **What:** <what was decided>
- **Why:** <reasoning if known>
- **Evidence:** <link/path>

### Decision 2: <title>
...

## Evolution Summary

<How the concept changed over time, key inflection points>

## Current State

<Where the concept stands now based on most recent evidence>

## Related Concepts

- <related concept 1> - see `/trace <concept1>`
- <related concept 2> - see `/trace <concept2>`

## Sources

### CASS Sessions
| Date | Session Path | Score |
|------|--------------|-------|
| ... | ... | ... |

### Handoff Documents
| Date | File | Context |
|------|------|---------|
| ... | ... | ... |

### Git Commits
| Date | SHA | Message |
|------|-----|---------|
| ... | ... | ... |

### Research/Learnings
| Date | File |
|------|------|
| ... | ... |

IF cass search returns 0 results:
  - Log: "No session transcripts mention '<concept>'"
  - Continue with other sources
  - Note in report: "Concept not found in session history"

IF .agents/handoff/ doesn't exist OR no matches:
  - Log: "No handoff documents mention '<concept>'"
  - Continue with other sources
  - Note in report: "Concept not documented in handoffs"

IF CASS returns >20 results:
  - Show top 10 by score
  - Ask user: "Many sessions mention this. Want to narrow by date range or workspace?"
  - Suggest related but more specific concepts

IF all 4 searches return nothing:
  - Report: "No provenance found for '<concept>'"
  - Suggest: "Try related terms: <suggestions>"
  - Ask: "Is this concept documented somewhere else?"

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