Given /trace :
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 parallel search agents using Task tool:
```
Tool: Task
Parameters:
subagent_type: "Explore"
model: "haiku"
description: "CASS search: "
prompt: |
Search session transcripts for:
Run this command:
cass search "" --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: "
prompt: |
Search handoff documents for:
1. List handoff files:
ls -la .agents/handoff/*.md 2>/dev/null
2. Search for concept mentions:
grep -l "" .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: "
prompt: |
Search git history for:
1. Search commit messages:
git log --oneline --grep="" | head -20
2. For interesting commits, get details:
git show --stat
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: "
prompt: |
Search research and learning artifacts for:
1. Search research docs:
grep -l "" .agents/research/*.md 2>/dev/null
2. Search learnings:
grep -l "" .agents/learnings/*.md 2>/dev/null
3. Search patterns:
grep -l "" .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.
```
Wait for all 4 agents to complete.
Step 2b: Git-Based Tracing (Commits/Refs)
For git refs, trace the commit history:
```bash
# Get commit details
git show --stat
# Get commit ancestry
git log --oneline --ancestry-path [..HEAD | head -20]
# Find related commits
git log --oneline --all --grep="$(git log -1 --format=%s [ | head -c 50)" | head -10]
```
Step 3: Build Timeline
Merge results from all sources into a single timeline:
```markdown
| 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 |
```
Deduplication rules:
- Same content within 24 hours = single event (note multiple sources)
- Same session ID = single event
- Preserve ALL sources as evidence
Sorting:
- Chronological order (oldest first)
- Show evolution of the concept over time
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-.md
```markdown
# Trace:
Date: YYYY-MM-DD
Query:
Sources searched: CASS, Handoffs, Git, Research
|