Find projects, code, and knowledge across git history, repos, docs, and Oracle.

MITAuto-check passedDevelopment

Install Trace

skills CLI
$ npx skills add Soul-Brews-Studio/arra-oracle-skills-cli --skill trace -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install Soul-Brews-Studio/arra-oracle-skills-cli trace --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/Soul-Brews-Studio/arra-oracle-skills-cli.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/trace .claude/skills/trace && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
trace
GitHub stars
123
Token cost
~2.9k tokens
SKILL.md length
733 words
Files
2 (incl. scripts)
Skills in repo
31
Repo updated
First seen
Licence
MIT

At a glance

Find projects, code, and knowledge across git history, repos, docs, and Oracle.

  • Works in 8 steps: Timestamp + Calculate Paths → Detect Target Repo → Create Trace Log Directory → …
  • User asks trace
  • SKILL.md covers Usage, Directory Structure, Step 0: Timestamp + Calculate… and Step 1: Detect Target Repo, plus 13 more sections
  • Runs Python scripts from its folder; calls python3

What it does

Trace is an agent skill from Soul-Brews-Studio/arra-oracle-skills-cli. 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).

Its SKILL.md is about 2.9k tokens, which your agent loads only when the skill is triggered. The skill folder holds 2 other files, including scripts (for example `scripts/dig.py`).

It sits in Development, covering Git workflow. The repository describes itself as: Install Oracle skills to Claude Code, OpenCode, Cursor, and 12+ AI coding agents. The licence is MIT.

When your agent uses it

  • User asks trace
  • Where is [project]
  • Needs to locate something across the codebase
  • Past sessions (use /dig)

Example prompts

  • “find project”
  • “where is [project]”
  • “search history”
  • “/trace”

Requirements

  • Python 3

Workflow steps

8 steps, taken from the step headings in SKILL.md.

  1. Timestamp + Calculate Paths
  2. Detect Target Repo
  3. Create Trace Log Directory
  4. Calculate Friction Score (Volt-inspired)
  5. Goal-Backward Check (GSD verifier-inspired)
  6. Write Trace Log
  7. Log to Oracle MCP
  8. Confirm trace log path (announce-mode — absolute paths required)

What it can do on your machine

Read from SKILL.md and the folder at commit 9feea09. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 1 file in scripts/ (Python), which the agent can run.

    Shell commands in SKILL.md call:

    • python3

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Trace loads about 2.9k tokens when it runs. Until then it costs about 107 tokens; SKILL.md has 733 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~107
When it runs · the whole SKILL.md, loaded when a task matches
~2.9k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from Soul-Brews-Studio/arra-oracle-skills-cli at commit 9feea09, republished under its MIT licence (© Soul-Brews-Studio). 733 words, ~2,929 tokens.

Download SKILL.mdSave it as .claude/skills/trace/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
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 foundSMeaning
Oracle1.0Frictionless — well-indexed, visible
Repo files0.7Present but not indexed
Git history0.5Buried — existed, hard to surface
Cross-repo0.3Hidden — lives elsewhere
Not found0.0Invisible — doesn't exist yet

C_offset — Completeness (from goal-backward check in Step 4):

ConfidenceC_offset
high+0.00
medium−0.10
low−0.20

Score table:

SituationScore
Oracle + high1.0
Oracle + medium0.9
Files + high0.7
Files + medium0.6
Git + high0.5
Git + medium0.4
Cross-repo + high0.3
Not found0.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.

Show full SKILL.md (289 more words)Show less

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:

RangeAction
0.9–1.0No action needed
0.6–0.89Consider oracle_learn indexing
0.4–0.59Distill + index this session
0.1–0.39Cross-repo consolidation needed
0.0Create / 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 ActionMeaningAI Response
/trace XFirst search--smart (Oracle first)
/trace X againStill seekingOracle knows
/trace X --deepReally need itWave execution
Found!RESONANCELog + score
Skill Separation
SkillPurposeWrites to
/traceFind + measureψ/memory/traces/ (logs)
/trace --digFind + measure + mine sessionsψ/memory/traces/ (logs)
/digMine sessions (standalone)Screen only (read-only)
/learnStudy reposψ/learn/ (docs)
/projectDevelop reposψ/incubate/ or active/

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


Summary

ModeSpeedScopeWaves
--oracleFastOracle only—
--smartMediumOracle → maybe deepAuto
--deepThoroughWave 1 (+ dig) + Wave 2 if needed2 + dig
--deep --dig(alias)Same as --deep—
Output fieldDescription
friction_score0.0–1.0 how hard to find
coveragedimensions searched
confidencedid trace answer the question

ARGUMENTS: $ARGUMENTS

© Soul-Brews-Studio, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file (scripts) in skills/trace of Soul-Brews-Studio/arra-oracle-skills-cli.

  • SKILL.md
  • scripts/dig.py

Open the folder on GitHubat commit 9feea09

Compare with similar skills

Trace next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Trace compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Trace this skillSoul-Brews-Studio/arra-oracle-skills-cli123—~2.9kAutomated safety check: PassMIT
Finishing a Development Branchobra/superpowers297k5 repos~1.9kAutomated safety check: PassMIT
Code Design Rationale Investigatorcursor/plugins10k9 repos~2.6kAutomated safety check: PassNone
Contributor-First PR MergeHKUDS/OpenHarness16k1 repos~847Automated safety check: PassMIT
Migrate Internal Package into GhostTryGhost/Ghost56k—~3.8kAutomated safety check: PassMIT
Create Pull Requestcline/cline70k1 repos~1.6kAutomated safety check: PassApache-2.0

Similar skills

  • Walks the last step of a branch: confirm tests pass, detect the git environment, ask how to integrate, carry out your choice and clean up the worktree.

    297k GitHub starsUsed in 5 repos~1.9k tokens
    DevelopmentAuto-check passed
  • Official

    Digs into why code is shaped the way it is by checking git history, pull requests and connected tools in parallel, then reporting a cited read on the tradeoffs.

    10k GitHub starsUsed in 9 repos~2.6k tokens
    DevelopmentAuto-check passed
  • Merges external GitHub pull requests while keeping the original author credited, and fixes conflicts after the merge instead of rewriting the contribution.

    16k GitHub starsUsed in 1 repo~847 tokens
    DevelopmentAuto-check passed
  • Moves a package from another TryGhost repository into Ghost as an internal workspace package while keeping its Git history, with checkpoints for the steps that need an administrator.

    56k GitHub stars~3.8k tokensUpdated today
    DevelopmentAuto-check passed
  • Opens a GitHub pull request from your current branch with the gh CLI, after reviewing the commits and diff and gathering the details the PR needs.

    70k GitHub starsUsed in 1 repo~1.6k tokens
    DevelopmentAuto-check passed
  • Writes Conventional Commits whose bodies carry action lines recording the intent, decisions and constraints behind a change, not only what changed.

    29k GitHub starsUsed in 1 repo~2.7k tokens
    DevelopmentAuto-check passed

More from Soul-Brews-Studio/arra-oracle-skills-cli

All 31 skills in this repo
  • Dig

    Soul-Brews-Studio/arra-oracle-skills-cli

    Mine Claude Code sessions — timeline, gaps, repo attribution, session history.

    123 GitHub stars~1.8k tokensUpdated 6 days ago
    Auto-check passed
  • Forward

    Soul-Brews-Studio/arra-oracle-skills-cli

    Hand off the current session to the next one. An agent skill from Soul-Brews-Studio/arra-oracle-skills-cli.

    123 GitHub stars~2.9k tokensUpdated 6 days ago
    Auto-check passed
  • Project

    Soul-Brews-Studio/arra-oracle-skills-cli

    Clone and track external repos. An agent skill from Soul-Brews-Studio/arra-oracle-skills-cli.

    123 GitHub stars~1.4k tokensUpdated 6 days ago
    Auto-check passed
  • Round Table

    Soul-Brews-Studio/arra-oracle-skills-cli

    Convene a Round Table (โต๊ะกลม): 3–8 souls — persona files, Oracles, or real people's DNA — debate ONE stakes-bearing decision over exactly 4 rounds (OPEN, DEEPEN, CONVERGE, VOTE), one subagent per…

    123 GitHub stars~2.1k tokensUpdated 6 days ago
    Auto-check passed
  • Soul

    Soul-Brews-Studio/arra-oracle-skills-cli

    Bring an Oracle into the current repo — its soul, ALL its skills and its expertise — by link, never by copy.

    123 GitHub stars~1.3k tokensUpdated 6 days ago
    Auto-check passed
  • Recap

    Soul-Brews-Studio/arra-oracle-skills-cli

    Session orientation and awareness — retro summaries, handoffs, git state, focus.

    123 GitHub stars~2.7k tokensUpdated 6 days ago
    Auto-check passed

Categories

Questions about Trace

What does Trace do?

Find projects, code, and knowledge across git history, repos, docs, and Oracle. Trace is an agent skill from Soul-Brews-Studio/arra-oracle-skills-cli. Find projects, code, and knowledge across git history, repos, docs, and Oracle.

When should I use Trace?

Trace fits situations like: user asks trace; where is [project]; needs to locate something across the codebase; past sessions (use /dig).

How do I install Trace in Claude Code?

Run `npx skills add Soul-Brews-Studio/arra-oracle-skills-cli --skill trace -a claude-code`. Or copy the skill folder (skills/trace in Soul-Brews-Studio/arra-oracle-skills-cli) into .claude/skills/trace in your project. Claude Code loads it when a task matches its description.

How do I install Trace in Codex?

Run `npx skills add Soul-Brews-Studio/arra-oracle-skills-cli --skill trace -a codex`. Or copy the skill folder (skills/trace in Soul-Brews-Studio/arra-oracle-skills-cli) into .agents/skills/trace in your project. Codex loads it when a task matches its description.

Can I use Trace in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add Soul-Brews-Studio/arra-oracle-skills-cli --skill trace -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/trace, .gemini/skills/trace, .github/skills/trace and .opencode/skills/trace in your project.

What does Trace need to run?

Going by SKILL.md and its folder, Trace needs Python for the scripts in its folder and the command-line tools its instructions call (python3). Our summary lists: Python 3.

Does Trace access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Trace safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Trace use?

Trace is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Trace use?

About 2.9k tokens (SKILL.md is roughly 12k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Trace?

Skills that share tags, products or a category with Trace: Finishing a Development Branch (obra/superpowers, 297k stars), Code Design Rationale Investigator (cursor/plugins, 10k stars), Contributor-First PR Merge (HKUDS/OpenHarness, 16k stars) and Migrate Internal Package into Ghost (TryGhost/Ghost, 56k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Trace?

Soul-Brews-Studio (a GitHub organization) maintains it in Soul-Brews-Studio/arra-oracle-skills-cli, which has 123 GitHub stars. The repository holds 31 skills in this directory. The repository was last updated on October 3, 2026.

Source: Soul-Brews-Studio/arra-oracle-skills-cli on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.