Skip to content
Skills Library
Programming · Research

trace

/trace

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

Licence
MIT
Last repository change
03.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 03.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/dig.py

What it does and when to use it

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

Triggers from the description

tracefind projectwhere is [project]search historypast sessionslearn repo

Arguments

/trace <query> [--oracle | --smart | --deep] [--dig]
Original author 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).

How it works

  1. Usage
  2. Directory Structure
  3. Step 0: Timestamp + Calculate Paths
  4. Step 1: Detect Target Repo
  5. Step 2: Create Trace Log Directory
  6. Mode 1: --oracle (Oracle Only)
  7. Mode 2: --smart (Default)
  8. Mode 3: --deep (Wave Execution + Session Mining)
  9. Mode 4: --deep --dig (Alias)
  10. Step 3: Calculate Friction Score (Volt-inspired)
Original SKILL.md headings · 449 lines, 1,722 words
SKILL.md preview
---
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

```bash
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
```bash
TARGET_REPO="$ROOT"
TARGET_NAME="$(basename $ROOT)"
```

### With --repo [path]: Local path
```bash
TARGET_REPO="[path]"
TARGET_NAME="$(basename [path])"
```

### With --repo [url]: Clone to ghq first
```bash
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

```bash
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 from the dig agent:

```markdown
## 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.

---

## Step 4: Goal-Backward Check (GSD verifier-inspired)

Before writing the trace log, ask:

> "Did this trace actually answer the original question?"

- **Yes** → confidence: high
- **Partial** (found related but not exact) → confidence: medium — note what's missing
- **No** → confidence: low — note what next step is needed

This prevents "found something → assume done". Omar stops here. Never crosses into deciding for jeera-p.

---

## Step 5: Write Trace Log

```markdown
---
query: "[query]"
target: "[TARGET_NAME]"
mode: [oracle|smart|deep]
timestamp: YYYY-MM-DD HH:MM
friction_score: [0.0–1.0]
coverage: [oracle, files, git, cross-repo, github]
confidence: [high|medium|low]
---

# Trace: [query]

**Target**: [TARGET_NAME]
**Mode**: [mode] | **Friction**: [score] | **Confidence**: [level]
**Time**: [timestamp]

## Oracle Results
[list results or "None"]

## Files Found
[list files or "None"]

## Git History
[list commits or "None"]

## GitHub Issues/PRs
[list or "None"]

## Cross-Repo Matches
[list or "None"]

## Oracle Memory
[list or "None"]

## Friction Analysis
**Score**: [0.0–1.0] — [interpretation]
**Coverage**: [dimensions searched]
**Goal check**: [Did this answer the question? What's missing?]

## Summary
[Key findings, next steps]
```

---

## Step 6: Log to Oracle MCP

```
arra_trace({
  query: "[query]",
  project: "[TARGET_NAME]",
  foundFiles: [...],
  foundCommits: [...],
  foundIssues: [...],
  friction_score: [0.0–1.0],
  confidence: "[high|medium|low]"
})
```

---

## Step 7: Confirm trace log path (announce-mode — absolute paths required)

# announce-mode → absolute path (no ψ/, no ~/, no $VAR, no ...).
# Use:  echo "marker: $RESOLVED_PATH"  — bash substitutes. See CONVENTIONS.md.

```bash
echo "🔍 Trace logged: $TRACE_FILE"
```

---

## Friction Score Reference

```
friction_score = S + C_offset    (clamped to [0.0, 1.0])

1.0 ████████████  Frictionless   — Oracle + high confidence
0.9 ███████████░  Near-perfect   — Oracle + medium confidence
0.7 ████████░░░░  Visible        — Files + high confidence
0.6 ███████░░░░░  Slightly buried — Files + medium confidence
0.5 ██████░░░░░░  Buried         — Git + high confidence
0.4 █████░░░░░░░  Buried-medium  — Git + medium confidence
0.3 ████░░░░░░░░  Hidden         — Cross-repo + high confidence
0.2 ███░░░░░░░░░  Very hidden    — Cross-repo + medium confidence
0.0 ░░░░░░░░░░░░  Invisible      — Not found anywhere
```

**Actionable zones**:
| Range | Action |
|-------|--------|
| 0.9–1.0 | No action needed |
| 0.6–0.89 | Consider `oracle_learn` indexing |
| 0.4–0.59 | Distill + index this session |
| 0.1–0.39 | Cross-repo consolidation needed |
| 0.0 | Create / document |

**Low score = signal**: this topic needs better indexing, documentation, or creation.
Omar surfaces this. jeera-p decides what to do about it.

---

## Philosophy

> Trace → Measure → Distill → Awakening

### The Seeking Signal

| User Action | Meaning | AI Response |
|-------------|---------|-------------|
| `/trace X` | First search | --smart (Oracle first) |
| `/trace X` again | Still seeking | Oracle knows |
| `/trace X --deep` | Really need it | Wave execution |
| Found! | **RESONANCE** | Log + score |

### Skill Separation

| Skill | Purpose | Writes to |
|-------|---------|-----------|
| `/trace` | Find + measure | ψ/memory/traces/ (logs) |
| `/trace --dig` | Find + measure + mine sessions | ψ/memory/traces/ (logs) |
| `/dig` | Mine sessions (standalone) | Screen only (read-only) |
| `/learn` | Study repos | ψ/learn/ (docs) |
| `/project` | Develop repos | ψ/incubate/ or active/ |

**Workflow**: `/trace` finds + measures → `/learn` studies → `/project` develops
**Combo**: `/trace --deep --dig` = find + mine in one shot

---

## Summary

| Mode | Speed | Scope | Waves |
|------|-------|-------|-------|
| `--oracle` | Fast | Oracle only | — |
| `--smart` | Medium | Oracle → maybe deep | Auto |
| `--deep` | Thorough | Wave 1 (+ dig) + Wave 2 if needed | 2 + dig |
| `--deep --dig` | (alias) | Same as --deep | — |

| Output field | Description |
|-------------|-------------|
| `friction_score` | 0.0–1.0 how hard to find |
| `coverage` | dimensions searched |
| `confidence` | did trace answer the question |

---

ARGUMENTS: $ARGUMENTS
Files in this package (2)
  • SKILL.md 12 KB
  • scripts/dig.py 5 KB

Versions

RepositoryScoreLicence
This page · Soul-Brews-Studio/arra-oracle-skills-cli100MIT
jeremylongshore/tons-of-skills-marketplace100MIT
r3dlex/oh-my-auggie100Apache-2.0
zereight/gitlab-mcp100MIT
proxify-dev/agentic-kit100MIT
biliboss/skills100MIT
oliver-kriska/claude-elixir-phoenix100MIT
moonklabs/aiwf100MIT
ccplugins/awesome-claude-code-plugins100Apache-2.0

Database snapshot: 13.11.2026 · package version 9c13ca9ac0ce (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100learn
    Explore a codebase with parallel Haiku agents — clone, read, and document. Modes — --fast (1 agent), default (3), --deep (5). Use when user says "learn [repo]", "explore codebase", "study this repo", or shares a GitHub URL to study. Do NOT trigger for finding projects (use…
  • 100dig
    Mine Claude Code sessions — timeline, gaps, repo attribution, session history. Use when user says "dig", "sessions", "past sessions", "timeline", "what did I work on", or wants to see session history. Do NOT trigger for finding code/projects (use /trace), exploring repos (use…
  • 100arch-oracle
    Use this skill when the user asks about git history, past decisions, why something was built a certain way, or needs to trace when/why a change was made. Provides historical awareness from git log, blame, and .ai/ memory.
  • 100git-mining
    This skill should be used when the user asks to "check git history", "trace code changes", "find when something was added", "correlate commits with sessions", "find hotspot files", or needs to mine git repository history for insights. Only applicable when the current project is a git repository.
  • 100ask
    Context-aware Q&A with auto context gathering. Use when: user has a quick question about codebase, git history, rules, docs, or skills during development. Not for: code changes (use feature-dev), code review (use codex-review-fast), deep research (use deep-research), full code…
  • 100oracle-verification
    Use when an agent needs to prepare, review, approve, or verify an Oracle Gateway task in a local project, or explain the outcome of an Oracle run.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.