Find projects, code, and knowledge across git history, repos, docs, and Oracle. Use when user asks "trace", "find project", "where is [project]", "search history", or needs to locate something across the codebase. Supports --oracle (fast), --smart (default), --deep (wave execution), --deep --dig (combo). Do NOT trigger for session mining or "past sessions" (use /dig), or codebase exploration "learn repo" (use /learn).
SKILL.md
/trace - Unified Discovery System
Find + Measure + Log + Distill
Usage
/trace [query] # Current repo (default --smart)
/trace [query] --oracle # Oracle only (fastest)
/trace [query] --deep # Wave execution (thorough)
/trace [query] --deep --dig # Combo: trace deep + dig session mining (parallel)
/trace [query] --repo [path] # Search specific local repo
/trace [query] --repo [url] # Clone to ghq, then search
/dig alone mines sessions. --dig flag on /trace runs both together.
If Oracle results < 3 → Auto-escalate to --deep mode
Mode 3: --deep (Wave Execution + Session Mining)
Two waves of parallel search + dig session mining. Each wave has fresh context (no rot).--deep --dig is now the same as --deep (dig is always included).
Wave 1 — Fast surface search + session mining (run in parallel)
Agent A: Current/Target Repo Files
You are searching for: [query]
TARGET REPO: [TARGET_REPO]
Search for:
- Files matching query (names, paths)
- Code/docs containing query
- Config files mentioning query
Return findings as text. Main agent compiles.
Agent B: Oracle Memory
You are searching for: [query]
PSI DIR: [ROOT]/ψ/
Search ψ/memory/ for:
- Learnings mentioning query
- Retrospectives mentioning query
- Previous trace logs for same query
Return findings as text. Main agent compiles.
Agent F: Session History (dig)
You are mining session history for: [query]
Run the dig script to get all sessions:
ENCODED_PWD=$(pwd | sed 's|^/|-|; s|[/.]|-|g')
PROJECT_BASE=$(ls -d "$HOME/.claude/projects/${ENCODED_PWD}" 2>/dev/null | head -1)
export PROJECT_DIRS="$PROJECT_BASE"
PARENT_ENCODED=$(echo "$ENCODED_PWD" | sed 's/-wt-[^/]*$//')
if [ "$PARENT_ENCODED" != "$ENCODED_PWD" ]; then
PARENT_BASE=$(ls -d "$HOME/.claude/projects/${PARENT_ENCODED}" 2>/dev/null | head -1)
[ -n "$PARENT_BASE" ] && export PROJECT_DIRS="$PROJECT_DIRS:$PARENT_BASE"
fi
for base in "$PROJECT_BASE" "$PARENT_BASE"; do
[ -z "$base" ] && continue
for wt in "$base"-wt-*(N); do
[ -d "$wt" ] && export PROJECT_DIRS="$PROJECT_DIRS:$wt"
done
done
python3 ~/.claude/skills/dig/scripts/dig.py 0 --deep
Then search the session data for mentions of: [query]
Look for:
- Sessions where this topic was worked on
- Timeline of when it was touched
- Which repos it appeared in
- How much time was spent
Return findings as text. Max 500 words.
After Wave 1: check if answer is sufficient.
Sufficient (clear answer found) → skip Wave 2, go to Step 3
Insufficient (< 3 results or answer unclear) → run Wave 2
Wave 2 — Deep search (run in parallel, only if Wave 1 insufficient)
Agent C: Git History
You are searching for: [query]
TARGET REPO: [TARGET_REPO]
Search git history:
- Commits mentioning query
- Files created/deleted matching query
- Branch names matching query
Run: git log --all --oneline --grep="[query]"
Return findings as text. Main agent compiles.
Agent D: Cross-Repo (ghq + ~/Code)
You are searching for: [query]
Search other repos:
- find $(ghq root) -maxdepth 3 -name "*[query]*" 2>/dev/null | head -20
- grep -r "[query]" ~/Code --include="*.md" -l 2>/dev/null | head -10
Return findings as text. Main agent compiles.
Agent E: GitHub Issues/PRs
You are searching for: [query]
TARGET REPO: [TARGET_REPO]
If repo has GitHub remote, run:
- gh issue list --search "[query]" --limit 10
- gh pr list --search "[query]" --limit 10
Return findings as text. Main agent compiles.
After both waves, main agent compiles all results → Step 3.
Mode 4: --deep --dig (Alias)
Same as --deep — dig is now always included in --deep mode (Agent F in Wave 1).
This flag is kept for backward compatibility but has no additional effect.
The trace log includes a Session History section from the dig agent:
## Session History (from /dig)
[Sessions where query appeared, timeline, time spent]
This goes between "Oracle Memory" and "Friction Analysis" in the trace log.
Step 3: Calculate Friction Score (Volt-inspired)
After search completes, calculate friction_score using the v2 formula:
friction_score = S + C_offset (clamped to [0.0, 1.0])
S — Source Score (highest-tier source with relevant result):
Where found
S
Meaning
Oracle
1.0
Frictionless — well-indexed, visible
Repo files
0.7
Present but not indexed
Git history
0.5
Buried — existed, hard to surface
Cross-repo
0.3
Hidden — lives elsewhere
Not found
0.0
Invisible — doesn't exist yet
C_offset — Completeness (from goal-backward check in Step 4):
Confidence
C_offset
high
+0.00
medium
−0.10
low
−0.20
Score table:
Situation
Score
Oracle + high
1.0
Oracle + medium
0.9
Files + high
0.7
Files + medium
0.6
Git + high
0.5
Git + medium
0.4
Cross-repo + high
0.3
Not found
0.0
Rule: S = highest-tier source that contained relevant result. Not found → 0.0 regardless of C_offset.
Also calculate coverage: how many of 5 dimensions were searched.
oracle, files, git, cross-repo, github — list which were checked.
