/trace

name: trace
description: 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).
argument-hint: "<query> [--oracle | --smart | --deep] [--dig]"

/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.

Directory Structure

ψ/memory/traces/
└── YYYY-MM-DD/              # Date folder
    └── HHMM_[query-slug].md # Time-prefixed trace log

**Trace logs are committed** - they become Oracle memory for future searches.

---

Step 0: Timestamp + Calculate Paths

date "+🕐 %H:%M %Z (%A %d %B %Y)"
ROOT="$(pwd)"
TODAY=$(date +%Y-%m-%d)
TIME=$(date +%H%M)

---

Step 1: Detect Target Repo

Default: Current repo

TARGET_REPO="$ROOT"
TARGET_NAME="$(basename $ROOT)"

With --repo [path]: Local path

TARGET_REPO="[path]"
TARGET_NAME="$(basename [path])"

With --repo [url]: Clone to ghq first

URL="[url]"
ghq get -u "$URL"
GHQ_ROOT=$(ghq root)
OWNER=$(echo "$URL" | sed -E 's|.*github.com/([^/]+)/.*|\1|')
REPO=$(echo "$URL" | sed -E 's|.*/([^/]+)(\.git)?$|\1|')
TARGET_REPO="$GHQ_ROOT/github.com/$OWNER/$REPO"
TARGET_NAME="$OWNER/$REPO"
echo "✓ Cloned to ghq: $TARGET_REPO"

**Note**: `/trace` only clones to ghq. Use `/learn` to create docs in ψ/learn/.

---

Step 2: Create Trace Log Directory

mkdir -p "$ROOT/ψ/memory/traces/$TODAY"
TRACE_FILE="$ROOT/ψ/memory/traces/$TODAY/${TIME}_[query-slug].md"

---

Mode 1: --oracle (Oracle Only)

**Fastest. Just Oracle MCP, no subagents.**

arra_search("[query]", limit=15)

Display results and done. Even if empty.

---

Mode 2: --smart (Default)

**Oracle first → auto-escalate if results < 3**

**Step 1**: Query Oracle first

arra_search("[query]", limit=10)

**Step 2**: Check result count

• If Oracle results >= 3 → Display and done
• 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