trace

Name: trace
Author: Soul-Brews-Studio

109stars55forks

How to install trace?

soul-brews-studio/arra-oracle-skills-cli/trace

$npx -y skills add Soul-Brews-Studio/arra-oracle-skills-cli --skill trace

Installs into the current project.

Summary

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 executio

Files · 1

View on GitHub

SKILL.md

1	# /trace - Unified Discovery System
2
3	Find + Measure + Log + Distill
4
5	## Usage
6
7	```
8	/trace [query] # Current repo (default --smart)
9	/trace [query] --oracle # Oracle only (fastest)
10	/trace [query] --deep # Wave execution (thorough)
11	/trace [query] --deep --dig # Combo: trace deep + dig session mining (parallel)
12	/trace [query] --repo [path] # Search specific local repo
13	/trace [query] --repo [url] # Clone to ghq, then search
14	```
15
16	> `/dig` alone mines sessions. `--dig` flag on `/trace` runs both together.
17
18	## Directory Structure
19
20	```
21	ψ/memory/traces/
22	└── YYYY-MM-DD/ # Date folder
23	└── HHMM_[query-slug].md # Time-prefixed trace log
24	```
25
26	Trace logs are committed - they become Oracle memory for future searches.
27
28	---
29
30	## Step 0: Timestamp + Calculate Paths
31
32	```bash
33	date "+🕐 %H:%M %Z (%A %d %B %Y)"
34	ROOT="$(pwd)"
35	TODAY=$(date +%Y-%m-%d)
36	TIME=$(date +%H%M)
37	```
38
39	---
40
41	## Step 1: Detect Target Repo
42
43	### Default: Current repo
44	```bash
45	TARGET_REPO="$ROOT"
46	TARGET_NAME="$(basename $ROOT)"
47	```
48
49	### With --repo [path]: Local path
50	```bash
51	TARGET_REPO="[path]"
52	TARGET_NAME="$(basename [path])"
53	```
54
55	### With --repo [url]: Clone to ghq first
56	```bash
57	URL="[url]"
58	ghq get -u "$URL"
59	GHQ_ROOT=$(ghq root)
60	OWNER=$(echo "$URL" \| sed -E 's\|.github.com/([^/]+)/.\|\1\|')
61	REPO=$(echo "$URL" \| sed -E 's\|.*/([^/]+)(\.git)?$\|\1\|')
62	TARGET_REPO="$GHQ_ROOT/github.com/$OWNER/$REPO"
63	TARGET_NAME="$OWNER/$REPO"
64	echo "✓ Cloned to ghq: $TARGET_REPO"
65	```
66
67	Note: `/trace` only clones to ghq. Use `/learn` to create docs in ψ/learn/.
68
69	---
70
71	## Step 2: Create Trace Log Directory
72
73	```bash
74	mkdir -p "$ROOT/ψ/memory/traces/$TODAY"
75	TRACE_FILE="$ROOT/ψ/memory/traces/$TODAY/${TIME}_[query-slug].md"
76	```
77
78	---
79
80	## Mode 1: --oracle (Oracle Only)
81
82	Fastest. Just Oracle MCP, no subagents.
83
84	```
85	arra_search("[query]", limit=15)
86	```
87
88	Display results and done. Even if empty.
89
90	---
91
92	## Mode 2: --smart (Default)
93
94	Oracle first → auto-escalate if results < 3
95
96	Step 1: Query Oracle first
97	```
98	arra_search("[query]", limit=10)
99	```
100
101	Step 2: Check result count
102	- If Oracle results >= 3 → Display and done
103	- If Oracle results < 3 → Auto-escalate to --deep mode
104
105	---
106
107	## Mode 3: --deep (Wave Execution + Session Mining)
108
109	Two waves of parallel search + dig session mining. Each wave has fresh context (no rot).
110	`--deep --dig` is now the same as `--deep` (dig is always included).
111
112	### Wave 1 — Fast surface search + session mining (run in parallel)
113
114	Agent A: Current/Target Repo Files
115	```
116	You are searching for: [query]
117	TARGET REPO: [TARGET_REPO]
118
119	Search for:
120	- Files matching query (names, paths)
121	- Code/docs containing query
122	- Config files mentioning query
123
124	Return findings as text. Main agent compiles.
125	```
126
127	Agent B: Oracle Memory
128	```
129	You are searching for: [query]
130	PSI DIR: [ROOT]/ψ/
131
132	Search ψ/memory/ for:
133	- Learnings mentioning query
134	- Retrospectives mentioning query
135	- Previous trace logs for same query
136
137	Return findings as text. Main agent compiles.
138	```
139
140	Agent F: Session History (dig)
141	```
142	You are mining session history for: [query]
143
144	Run the dig script to get all sessions:
145	ENCODED_PWD=$(pwd \| sed 's\|^/\|-\|; s\|[/.]\|-\|g')
146	PROJECT_BASE=$(ls -d "$HOME/.claude/projects/${ENCODED_PWD}" 2>/dev/null \| head -1)
147	export PROJECT_DIRS="$PROJECT_BASE"
148
149	PARENT_ENCODED=$(echo "$ENCODED_PWD" \| sed 's/-wt-[^/]*$//')
150	if [ "$PARENT_ENCODED" != "$ENCODED_PWD" ]; then
151	PARENT_BASE=$(ls -d "$HOME/.claude/projects/${PARENT_ENCODED}" 2>/dev/null \| head -1)
152	[ -n "$PARENT_BASE" ] && export PROJECT_DIRS="$PROJECT_DIRS:$PARENT_BASE"
153	fi
154
155	for base in "$PROJECT_BASE" "$PARENT_BASE"; do
156	[ -z "$base" ] && continue
157	for wt in "$base"-wt-*(N); do
158	[ -d "$wt" ] && export PROJECT_DIRS="$PROJECT_DIRS:$wt"
159	done
160	done
161
162	python3 ~/.claude/skills/dig/scripts/dig.py 0 --deep
163
164	Then search the session data for mentions of: [query]
165	Look for:
166	- Sessions where this topic was worked on
167	- Timeline of when it was touched
168	- Which repos it appeared in
169	- How much time was spent
170
171	Return findings as text. Max 500 words.
172	```
173
174	After Wave 1: check if answer is sufficient.
175	- Sufficient (clear answer found) → skip Wave 2, go to Step 3
176	- Insufficient (< 3 results or answer unclear) → run Wave 2
177
178	### Wave 2 — Deep search (run in parallel, only if Wave 1 insufficient)
179
180	Agent C: Git History
181	```
182	You are searching for: [query]
183	TARGET REPO: [TARGET_REPO]
184
185	Search git history:
186	- Commits mentioning query
187	- Files created/deleted matching query
188	- B

People who liked this also viewed

6 picks

Type

trace

109stars55forks

View on GitHub

How to install trace?

soul-brews-studio/arra-oracle-skills-cli/trace

$npx -y skills add Soul-Brews-Studio/arra-oracle-skills-cli --skill trace

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# /trace - Unified Discovery System
2
3	Find + Measure + Log + Distill
4
5	## Usage
6
7	```
8	/trace [query] # Current repo (default --smart)
9	/trace [query] --oracle # Oracle only (fastest)
10	/trace [query] --deep # Wave execution (thorough)
11	/trace [query] --deep --dig # Combo: trace deep + dig session mining (parallel)
12	/trace [query] --repo [path] # Search specific local repo
13	/trace [query] --repo [url] # Clone to ghq, then search
14	```
15
16	> `/dig` alone mines sessions. `--dig` flag on `/trace` runs both together.
17
18	## Directory Structure
19
20	```
21	ψ/memory/traces/
22	└── YYYY-MM-DD/ # Date folder
23	└── HHMM_[query-slug].md # Time-prefixed trace log
24	```
25
26	Trace logs are committed - they become Oracle memory for future searches.
27
28	---
29
30	## Step 0: Timestamp + Calculate Paths
31
32	```bash
33	date "+🕐 %H:%M %Z (%A %d %B %Y)"
34	ROOT="$(pwd)"
35	TODAY=$(date +%Y-%m-%d)
36	TIME=$(date +%H%M)
37	```
38
39	---
40
41	## Step 1: Detect Target Repo
42
43	### Default: Current repo
44	```bash
45	TARGET_REPO="$ROOT"
46	TARGET_NAME="$(basename $ROOT)"
47	```
48
49	### With --repo [path]: Local path
50	```bash
51	TARGET_REPO="[path]"
52	TARGET_NAME="$(basename [path])"
53	```
54
55	### With --repo [url]: Clone to ghq first
56	```bash
57	URL="[url]"
58	ghq get -u "$URL"
59	GHQ_ROOT=$(ghq root)
60	OWNER=$(echo "$URL" \| sed -E 's\|.github.com/([^/]+)/.\|\1\|')
61	REPO=$(echo "$URL" \| sed -E 's\|.*/([^/]+)(\.git)?$\|\1\|')
62	TARGET_REPO="$GHQ_ROOT/github.com/$OWNER/$REPO"
63	TARGET_NAME="$OWNER/$REPO"
64	echo "✓ Cloned to ghq: $TARGET_REPO"
65	```
66
67	Note: `/trace` only clones to ghq. Use `/learn` to create docs in ψ/learn/.
68
69	---
70
71	## Step 2: Create Trace Log Directory
72
73	```bash
74	mkdir -p "$ROOT/ψ/memory/traces/$TODAY"
75	TRACE_FILE="$ROOT/ψ/memory/traces/$TODAY/${TIME}_[query-slug].md"
76	```
77
78	---
79
80	## Mode 1: --oracle (Oracle Only)
81
82	Fastest. Just Oracle MCP, no subagents.
83
84	```
85	arra_search("[query]", limit=15)
86	```
87
88	Display results and done. Even if empty.
89
90	---
91
92	## Mode 2: --smart (Default)
93
94	Oracle first → auto-escalate if results < 3
95
96	Step 1: Query Oracle first
97	```
98	arra_search("[query]", limit=10)
99	```
100
101	Step 2: Check result count
102	- If Oracle results >= 3 → Display and done
103	- If Oracle results < 3 → Auto-escalate to --deep mode
104
105	---
106
107	## Mode 3: --deep (Wave Execution + Session Mining)
108
109	Two waves of parallel search + dig session mining. Each wave has fresh context (no rot).
110	`--deep --dig` is now the same as `--deep` (dig is always included).
111
112	### Wave 1 — Fast surface search + session mining (run in parallel)
113
114	Agent A: Current/Target Repo Files
115	```
116	You are searching for: [query]
117	TARGET REPO: [TARGET_REPO]
118
119	Search for:
120	- Files matching query (names, paths)
121	- Code/docs containing query
122	- Config files mentioning query
123
124	Return findings as text. Main agent compiles.
125	```
126
127	Agent B: Oracle Memory
128	```
129	You are searching for: [query]
130	PSI DIR: [ROOT]/ψ/
131
132	Search ψ/memory/ for:
133	- Learnings mentioning query
134	- Retrospectives mentioning query
135	- Previous trace logs for same query
136
137	Return findings as text. Main agent compiles.
138	```
139
140	Agent F: Session History (dig)
141	```
142	You are mining session history for: [query]
143
144	Run the dig script to get all sessions:
145	ENCODED_PWD=$(pwd \| sed 's\|^/\|-\|; s\|[/.]\|-\|g')
146	PROJECT_BASE=$(ls -d "$HOME/.claude/projects/${ENCODED_PWD}" 2>/dev/null \| head -1)
147	export PROJECT_DIRS="$PROJECT_BASE"
148
149	PARENT_ENCODED=$(echo "$ENCODED_PWD" \| sed 's/-wt-[^/]*$//')
150	if [ "$PARENT_ENCODED" != "$ENCODED_PWD" ]; then
151	PARENT_BASE=$(ls -d "$HOME/.claude/projects/${PARENT_ENCODED}" 2>/dev/null \| head -1)
152	[ -n "$PARENT_BASE" ] && export PROJECT_DIRS="$PROJECT_DIRS:$PARENT_BASE"
153	fi
154
155	for base in "$PROJECT_BASE" "$PARENT_BASE"; do
156	[ -z "$base" ] && continue
157	for wt in "$base"-wt-*(N); do
158	[ -d "$wt" ] && export PROJECT_DIRS="$PROJECT_DIRS:$wt"
159	done
160	done
161
162	python3 ~/.claude/skills/dig/scripts/dig.py 0 --deep
163
164	Then search the session data for mentions of: [query]
165	Look for:
166	- Sessions where this topic was worked on
167	- Timeline of when it was touched
168	- Which repos it appeared in
169	- How much time was spent
170
171	Return findings as text. Max 500 words.
172	```
173
174	After Wave 1: check if answer is sufficient.
175	- Sufficient (clear answer found) → skip Wave 2, go to Step 3
176	- Insufficient (< 3 results or answer unclear) → run Wave 2
177
178	### Wave 2 — Deep search (run in parallel, only if Wave 1 insufficient)
179
180	Agent C: Git History
181	```
182	You are searching for: [query]
183	TARGET REPO: [TARGET_REPO]
184
185	Search git history:
186	- Commits mentioning query
187	- Files created/deleted matching query
188	- B

People who liked this also viewed

6 picks

Type