Soul-Brews-Studio/trace

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

---

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

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

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