learn

Name: learn
Author: Soul-Brews-Studio

109stars55forks

How to install learn?

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

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

Installs into the current project.

Summary

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

Files · 1

View on GitHub

SKILL.md

1	# /learn - Deep Dive Learning Pattern
2
3	Explore a codebase with 3 parallel Haiku agents → create organized documentation.
4
5	## Usage
6
7	```
8	/learn [url] # Auto: clone via ghq, symlink origin/, then explore
9	/learn [slug] # Use slug from ψ/memory/slugs.yaml
10	/learn [repo-path] # Path to repo
11	/learn [repo-name] # Finds in ψ/learn/owner/repo
12	/learn --init # Restore all origins after git clone (like submodule init)
13	```
14
15	## Depth Modes
16
17	\| Flag \| Agents \| Files \| Use Case \|
18	\|------\|--------\|-------\|----------\|
19	\| `--fast` \| 1 \| 1 overview \| Quick scan, "what is this?" \|
20	\| (default) \| 3 \| 3 docs \| Normal exploration \|
21	\| `--deep` \| 5 \| 5 docs \| Master complex codebases \|
22
23	```
24	/learn --fast [target] # Quick overview (1 agent, ~2 min)
25	/learn [target] # Standard (3 agents, ~5 min)
26	/learn --deep [target] # Deep dive (5 agents, ~10 min)
27	```
28
29	## Directory Structure
30
31	```
32	ψ/learn/
33	├── .origins # Manifest of learned repos (committed)
34	└── owner/
35	└── repo/
36	├── origin # Symlink to ghq source (gitignored)
37	├── repo.md # Hub file - links to all sessions (committed)
38	└── YYYY-MM-DD/ # Date folder
39	├── 1349_ARCHITECTURE.md # Time-prefixed files
40	├── 1349_CODE-SNIPPETS.md
41	├── 1349_QUICK-REFERENCE.md
42	├── 1520_ARCHITECTURE.md # Second run same day
43	└── ...
44	```
45
46	Multiple learnings: Each run gets time-prefixed files (HHMM_), nested in date folder.
47
48	Offload source, keep docs:
49	```bash
50	unlink ψ/learn/owner/repo/origin # Remove symlink
51	ghq rm owner/repo # Remove source
52	# Docs remain in ψ/learn/owner/repo/
53	```
54
55	## /learn --init
56
57	Restore all origins after cloning (like `git submodule init`):
58
59	```bash
60	ROOT="$(pwd)"
61	# Read .origins manifest and restore symlinks
62	while read repo; do
63	ghq get -u "https://github.com/$repo"
64	OWNER=$(dirname "$repo")
65	REPO=$(basename "$repo")
66	mkdir -p "$ROOT/ψ/learn/$OWNER/$REPO"
67	ln -sf "$(ghq root)/github.com/$repo" "$ROOT/ψ/learn/$OWNER/$REPO/origin"
68	echo "✓ Restored: $repo"
69	done < "$ROOT/ψ/learn/.origins"
70	```
71
72	## Step 0: Detect Input Type + Resolve Path
73
74	CRITICAL: Capture ABSOLUTE paths first (before spawning any agents):
75	```bash
76	date "+🕐 %H:%M %Z (%A %d %B %Y)" && ROOT="$(pwd)"
77	echo "Learning from: $ROOT"
78	```
79
80	IMPORTANT FOR SUBAGENTS:
81	When spawning Haiku agents, you MUST give them TWO literal paths:
82	1. SOURCE_DIR (where to READ code) - the `origin/` symlink
83	2. DOCS_DIR (where to WRITE docs) - the parent directory, NOT inside origin/
84
85	⚠️ THE BUG: If you only give agents `origin/` path, they cd into it and write there → files end up in WRONG repo!
86
87	FIX: Always give BOTH paths as LITERAL absolute values (no variables!):
88
89	Example: ROOT=/home/user/ghq/.../my-oracle, learning acme-corp/cool-library, TODAY=2026-02-04, TIME=1349:
90	```
91	READ from: .../ψ/learn/acme-corp/cool-library/origin/
92	WRITE to: .../ψ/learn/acme-corp/cool-library/2026-02-04/1349_[FILENAME].md
93	```
94
95	Tell each agent: "Read from [SOURCE_DIR]. Write to [DOCS_DIR]/[TIME]_[FILENAME].md"
96
97	### If URL (http* or owner/repo format)
98
99	Clone, create docs dir, symlink origin, update manifest:
100	```bash
101	# Replace [URL] with actual URL
102	URL="[URL]"
103	ROOT="$(pwd)" # CRITICAL: Save current directory!
104	ghq get -u "$URL" && \
105	GHQ_ROOT=$(ghq root) && \
106	OWNER=$(echo "$URL" \| sed -E 's\|.github.com/([^/]+)/.\|\1\|') && \
107	REPO=$(echo "$URL" \| sed -E 's\|.*/([^/]+)(\.git)?$\|\1\|') && \
108	mkdir -p "$ROOT/ψ/learn/$OWNER/$REPO" && \
109	ln -sf "$GHQ_ROOT/github.com/$OWNER/$REPO" "$ROOT/ψ/learn/$OWNER/$REPO/origin" && \
110	echo "$OWNER/$REPO" >> "$ROOT/ψ/learn/.origins" && \
111	sort -u -o "$ROOT/ψ/learn/.origins" "$ROOT/ψ/learn/.origins" && \
112	echo "✓ Ready: $ROOT/ψ/learn/$OWNER/$REPO/origin → source"
113	```
114
115	Verify:
116	```bash
117	ls -la "$ROOT/ψ/learn/$OWNER/$REPO/"
118	```
119
120	> Note: Grep tool doesn't follow symlinks. Use: `rg -L "pattern" ψ/learn/owner/repo/origin/`
121
122	### Then resolve path:
123	```bash
124	# Find by name (searches origin symlinks)
125	find ψ/learn -name "origin" -type l \| xargs -I{} dirname {} \| grep -i "$INPUT" \| head -1
126	```
127
128	## Scope
129
130	For external repos: Clone with script first, then explore via `origin/`
131	For local projects (in `specs/`, `ψ/lib/`): Read directly
132
133	## Step 1: Detect Mode & Calculate Paths
134
135	Check arguments for `--fast` or `--deep`:
136	- `--fast` → Single overview agent
137	- `--deep` → 5 parallel agents
138	- (neither) → 3 parallel agents (default)
139
140	**Calculate ACTUAL paths (replace variables with real values

People who liked this also viewed

6 picks

Type

learn

109stars55forks

View on GitHub

How to install learn?

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

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

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# /learn - Deep Dive Learning Pattern
2
3	Explore a codebase with 3 parallel Haiku agents → create organized documentation.
4
5	## Usage
6
7	```
8	/learn [url] # Auto: clone via ghq, symlink origin/, then explore
9	/learn [slug] # Use slug from ψ/memory/slugs.yaml
10	/learn [repo-path] # Path to repo
11	/learn [repo-name] # Finds in ψ/learn/owner/repo
12	/learn --init # Restore all origins after git clone (like submodule init)
13	```
14
15	## Depth Modes
16
17	\| Flag \| Agents \| Files \| Use Case \|
18	\|------\|--------\|-------\|----------\|
19	\| `--fast` \| 1 \| 1 overview \| Quick scan, "what is this?" \|
20	\| (default) \| 3 \| 3 docs \| Normal exploration \|
21	\| `--deep` \| 5 \| 5 docs \| Master complex codebases \|
22
23	```
24	/learn --fast [target] # Quick overview (1 agent, ~2 min)
25	/learn [target] # Standard (3 agents, ~5 min)
26	/learn --deep [target] # Deep dive (5 agents, ~10 min)
27	```
28
29	## Directory Structure
30
31	```
32	ψ/learn/
33	├── .origins # Manifest of learned repos (committed)
34	└── owner/
35	└── repo/
36	├── origin # Symlink to ghq source (gitignored)
37	├── repo.md # Hub file - links to all sessions (committed)
38	└── YYYY-MM-DD/ # Date folder
39	├── 1349_ARCHITECTURE.md # Time-prefixed files
40	├── 1349_CODE-SNIPPETS.md
41	├── 1349_QUICK-REFERENCE.md
42	├── 1520_ARCHITECTURE.md # Second run same day
43	└── ...
44	```
45
46	Multiple learnings: Each run gets time-prefixed files (HHMM_), nested in date folder.
47
48	Offload source, keep docs:
49	```bash
50	unlink ψ/learn/owner/repo/origin # Remove symlink
51	ghq rm owner/repo # Remove source
52	# Docs remain in ψ/learn/owner/repo/
53	```
54
55	## /learn --init
56
57	Restore all origins after cloning (like `git submodule init`):
58
59	```bash
60	ROOT="$(pwd)"
61	# Read .origins manifest and restore symlinks
62	while read repo; do
63	ghq get -u "https://github.com/$repo"
64	OWNER=$(dirname "$repo")
65	REPO=$(basename "$repo")
66	mkdir -p "$ROOT/ψ/learn/$OWNER/$REPO"
67	ln -sf "$(ghq root)/github.com/$repo" "$ROOT/ψ/learn/$OWNER/$REPO/origin"
68	echo "✓ Restored: $repo"
69	done < "$ROOT/ψ/learn/.origins"
70	```
71
72	## Step 0: Detect Input Type + Resolve Path
73
74	CRITICAL: Capture ABSOLUTE paths first (before spawning any agents):
75	```bash
76	date "+🕐 %H:%M %Z (%A %d %B %Y)" && ROOT="$(pwd)"
77	echo "Learning from: $ROOT"
78	```
79
80	IMPORTANT FOR SUBAGENTS:
81	When spawning Haiku agents, you MUST give them TWO literal paths:
82	1. SOURCE_DIR (where to READ code) - the `origin/` symlink
83	2. DOCS_DIR (where to WRITE docs) - the parent directory, NOT inside origin/
84
85	⚠️ THE BUG: If you only give agents `origin/` path, they cd into it and write there → files end up in WRONG repo!
86
87	FIX: Always give BOTH paths as LITERAL absolute values (no variables!):
88
89	Example: ROOT=/home/user/ghq/.../my-oracle, learning acme-corp/cool-library, TODAY=2026-02-04, TIME=1349:
90	```
91	READ from: .../ψ/learn/acme-corp/cool-library/origin/
92	WRITE to: .../ψ/learn/acme-corp/cool-library/2026-02-04/1349_[FILENAME].md
93	```
94
95	Tell each agent: "Read from [SOURCE_DIR]. Write to [DOCS_DIR]/[TIME]_[FILENAME].md"
96
97	### If URL (http* or owner/repo format)
98
99	Clone, create docs dir, symlink origin, update manifest:
100	```bash
101	# Replace [URL] with actual URL
102	URL="[URL]"
103	ROOT="$(pwd)" # CRITICAL: Save current directory!
104	ghq get -u "$URL" && \
105	GHQ_ROOT=$(ghq root) && \
106	OWNER=$(echo "$URL" \| sed -E 's\|.github.com/([^/]+)/.\|\1\|') && \
107	REPO=$(echo "$URL" \| sed -E 's\|.*/([^/]+)(\.git)?$\|\1\|') && \
108	mkdir -p "$ROOT/ψ/learn/$OWNER/$REPO" && \
109	ln -sf "$GHQ_ROOT/github.com/$OWNER/$REPO" "$ROOT/ψ/learn/$OWNER/$REPO/origin" && \
110	echo "$OWNER/$REPO" >> "$ROOT/ψ/learn/.origins" && \
111	sort -u -o "$ROOT/ψ/learn/.origins" "$ROOT/ψ/learn/.origins" && \
112	echo "✓ Ready: $ROOT/ψ/learn/$OWNER/$REPO/origin → source"
113	```
114
115	Verify:
116	```bash
117	ls -la "$ROOT/ψ/learn/$OWNER/$REPO/"
118	```
119
120	> Note: Grep tool doesn't follow symlinks. Use: `rg -L "pattern" ψ/learn/owner/repo/origin/`
121
122	### Then resolve path:
123	```bash
124	# Find by name (searches origin symlinks)
125	find ψ/learn -name "origin" -type l \| xargs -I{} dirname {} \| grep -i "$INPUT" \| head -1
126	```
127
128	## Scope
129
130	For external repos: Clone with script first, then explore via `origin/`
131	For local projects (in `specs/`, `ψ/lib/`): Read directly
132
133	## Step 1: Detect Mode & Calculate Paths
134
135	Check arguments for `--fast` or `--deep`:
136	- `--fast` → Single overview agent
137	- `--deep` → 5 parallel agents
138	- (neither) → 3 parallel agents (default)
139
140	**Calculate ACTUAL paths (replace variables with real values

People who liked this also viewed

6 picks

Type