| name | github-project-researcher |
| description | Use when researching GitHub projects — analyzing capabilities, architecture, security, fitness (including cross-domain), competitors, cloning to local library, generating RESEARCH.md. Self-evolving through accumulated knowledge. |
GitHub Project Researcher
Prompt-only skill for GitHub project research. Analyze, score, compare — output RESEARCH.md.
Clone base: ~/.github-researcher/projects/{owner}/{repo}/
Butler contract: RESEARCH.md at ~/.github-researcher/projects/{owner}/{repo}/RESEARCH.md
What should I do? (Decision Tree)
User's request
│
├─ Quick Assessment (5 min)
│ Steps: 1 → 2 → README scan → verdict
│ Template: templates/research-quick.md
│
├─ Deep Dive (30 min) ← DEFAULT / Butler mode
│ Steps: 1 → 2 → 3.0 → 3/3D → 4 → 5 → 6
│ Template: templates/research-deep.md
│
├─ Security Audit (15 min)
│ Steps: 1 → 2 → 3-security → 4 (Security Posture only)
│ Template: templates/research-security.md
│ Optional: SlowMist enhanced review (Web3/agent/strict mode)
│
├─ Architecture Discovery (20 min)
│ Steps: 1 → 2 → 3-architecture → document
│ Template: templates/research-deep.md (Architecture focus)
│
├─ Cross-Domain Eval (25 min)
│ Steps: 1 → 2 → 3 → 4 → 4.5
│ Template: templates/research-deep.md + Domain Fitness section
│
└─ Competitor Analysis (30 min)
Steps: 1 → 2 → 3 → 4 → 5 → 7
Template: templates/research-deep.md + COMPETITORS.md
⚠️ Safety Rules (inline, mandatory)
Rule 1: TodoList before starting
Create TodoList with all planned steps. Mark in_progress before starting each, completed immediately after.
Rule 2: Language auto-detect is MANDATORY
Run language detection before ANY grep. Set --include flags based on result. Never hardcode *.py.
find . -type f -not -path './.git/*' -not -path './node_modules/*' -not -path './venv/*' \
| sed 's/.*\.//' | sort | uniq -c | sort -rn | head -15
Rule 3: Graceful degradation — never retry failed strategy
gh auth status
├─ ✅ Authenticated → Strategy A (gh CLI)
├─ ❌ Not installed/unauth → Strategy B (webfetch) — do NOT retry gh
└─ ⚠️ Rate limited → Strategy C (curl, 60 req/hr) — do NOT retry gh
Rule 4: Evidence-based — every claim needs data
No fabricated metrics. No "approximately" without actual counts. Every score backed by checklist.
Rule 5: Large repo / edge case handling
- Repo >100MB →
git clone --depth 1
- Monorepo → detect workspace config, scope to dominant package
- Archived → 1-paragraph verdict, skip steps 2-7
- Empty repo → minimal RESEARCH.md, skip analysis
Use Case Table
| Pattern | Steps | Time | Template |
|---|
| Quick Assessment | 1 → 2 → README → verdict | 5 min | research-quick.md |
| Deep Dive | Full 1-6 | 30 min | research-deep.md |
| Security Audit | 1 → 2 → 3-security → scoring | 15 min | research-security.md |
| Architecture Discovery | 1 → 2 → 3-architecture | 20 min | research-deep.md |
| Cross-Domain Eval | 1-4 → 4.5 | 25 min | research-deep.md |
| Competitor Analysis | 1-5 → 7 | 30 min | research-deep.md |
| Ecosystem Audit | Extract claims → parallel librarians | 15 min | (appendix) |
| Documentation Project | 1 → 2 → 3.0 → 3d-docs | 20 min | research-deep.md |
Workflow Overview
1. Fetch Info → 2. Clone → 3.0 Type Gate
↓
┌───────────┴───────────┐
↓ ↓
3d-docs Analysis 3-analysis
├─ IA mapping ├─ 3.1 Structure
├─ Build pipeline ├─ 3.2 Dependencies
├─ Coverage ├─ 3.4 Quality
└─ Writing quality └─ 3.4.1 AI detection
└───────────┬───────────┘
↓
3-security ──── 3-architecture
↓ ↓
4. Fitness (/80 + Security /20)
4.2 Ecosystem (if claims >5)
4.5 Domain Fitness (if cross-domain)
↓
5. Generate RESEARCH.md → 6. Update KB → 7. Competitors
When to Open Sub-Documents
| File | Open When |
|---|
steps/01-fetch.md | Starting any research — strategy selection |
steps/02-clone.md | After fetch — clone + edge cases |
steps/03-type-gate.md | After clone — route to code vs docs |
steps/03-analysis.md | Code project — structure, deps, quality |
steps/03d-docs.md | Docs project — IA, build, coverage |
steps/03-security.md | Security audit or code analysis; includes SlowMist escalation triggers |
steps/03-architecture.md | Complex project — patterns, hierarchy |
steps/04-fitness.md | Before evaluation — scoring checklists |
steps/05-report.md | Writing RESEARCH.md — template reference |
steps/06-kb.md | After report — KB update rules |
steps/07-competitors.md | Competitor analysis requested |
templates/research-quick.md | Quick assessment output |
templates/research-deep.md | Full deep dive output |
templates/research-security.md | Security audit output |
templates/kb-entry.md | Per-project KB entry format |
Edge Cases
| Case | Action |
|---|
| Private repo | Requires gh auth login — Strategy B/C cannot access |
| Archived repo | 1-paragraph verdict, skip steps 2-7 |
| Empty repo | Minimal RESEARCH.md, skip analysis |
| Monorepo | Detect workspace config, scope to dominant package |
| No README | Use description + topics from gh/webfetch |
| Binary-heavy | Focus on config/build files, note limited analysis |
| All strategies fail | Report errors, ask user to verify gh auth login |
Verification Checklist (after Step 5)
