tomevault-io GitHub Research Skill
Use when auditing an unfamiliar codebase for the first time — architecture mapping, undocumented features, configuration gaps. NOT for catching up on your own branch (use catchup for that). BrainLayer first — check memory before reading files.
Step 0: BrainLayer First
brain_search("<repo-name> architecture")
brain_search("<repo-name> patterns decisions")
brain_entity("<repo-name>")
If BrainLayer has it → start from what you know, fill gaps only. If not → proceed to Phase 1.
Phase 1: Structure Discovery
# Directory tree (2 levels, ignore noise)
tree -L 2 -I 'node_modules|.git|dist|build|.next' .
# Config files
find . -maxdepth 2 \( -name "*.json" -o -name "*.yaml" -o -name "*.toml" \) | head -20
# Docs
find . -name "*.md" -not -path "*/node_modules/*" | head -20
# Monorepo?
ls packages/ 2>/dev/null || ls apps/ 2>/dev/null || echo "Not a monorepo"
Phase 2: Entry Points
# Package scripts and main
cat package.json 2>/dev/null | grep -A10 '"scripts"\|"main"\|"bin"' | head -30
# TypeScript entry points
find . -name "index.ts" -not -path "*/node_modules/*" | head -10
# Rust entry points
find . -name "main.rs" -o -name "lib.rs" | grep -v target | head -10
Phase 3: Key Files (READ THESE)
Always read if they exist:
README.md— official docsCLAUDE.md— AI context (critical)package.json/Cargo.toml— deps and scripts- Main entry file
Phase 4: Function/Command Discovery
# TypeScript exports
grep -r "export function\|export const\|export async" --include="*.ts" . | grep -v node_modules | head -30
# Shell functions
grep -r "^function \|^[a-z_]*() {" --include="*.zsh" --include="*.sh" . | head -30
# CLI commands
grep -r "\.command(\|addCommand\|program\." --include="*.ts" . | grep -v node_modules | head -20
# Rust public API
grep -r "^pub fn\|^pub async fn" --include="*.rs" . | grep -v target | head -20
Phase 5: Golem Ecosystem Context
When researching any golem repo, check cross-repo dependencies:
| Repo | Path | Purpose |
|---|---|---|
| orchestrator | ~/Gits/orchestrator | orcClaude — cross-repo coordination |
| golems | ~/Gits/golems | Monorepo — coach, shared, services |
| brainlayer | ~/Gits/brainlayer | Memory layer — BrainLayer MCP |
| voicelayer | ~/Gits/voicelayer | Voice I/O — VoiceBar + MCP |
| golem-terminal | ~/Gits/golem-terminal | Native macOS terminal for agents |
| golems-dashboard | ~/Gits/golems-dashboard | BrainLayer entity browser |
Output Format
Write findings to docs.local/research/<repo>-research.md, then brain_store key findings with tags ["research", "<repo>"].
Critique Waves Pattern
For thorough research, run multiple passes:
- Wave 1: BrainLayer recall + structure (tree, find)
- Wave 2: Read key files (README, CLAUDE.md, package.json)
- Wave 3: Function/command extraction
- Wave 4: Cross-reference with docs, find gaps
- Wave 5: brain_store findings
Each wave writes to separate sections, then consolidate.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.