tkersey/research-software

research-software — Software Research

Rules: Latest STABLE tag (not main). Filter to 2025-2026. Code > Docs. Skip Stack Overflow.

Output First

Every research produces this structure:

## [Tool] vX.Y.Z (YYYY-MM-DD)

**Repo:** github.com/org/repo @ abc123

### Commands
| Task | Command | Notes |
|------|---------|-------|

### Config
| Option | Default | Notes |
|--------|---------|-------|

### Env Vars
| Variable | Purpose |
|----------|---------|

### Gotchas
- [problem]: [fix]. Source: [PR/issue/code]

### Sources
- Code: [file:line]
- PRs: #123, #456
- Posts: [url]

---

THE PROMPT

Research [TOOL] for [PURPOSE].
Clone to /tmp, checkout latest stable tag.
Spawn Explore agent on source. Find: CLI, config, hidden flags, env vars.
Parallel: GitHub PRs/issues, web search "[tool] 2025".
Output: skill-ready markdown.

---

Pipeline

# 0. Detect context (if in a project)
# Check package.json, Cargo.toml, pyproject.toml for existing versions

# 1. Clone + stable tag
git clone --depth 1 https://github.com/[org]/[repo] /tmp/[repo]-research
cd /tmp/[repo]-research && git fetch --tags && git checkout $(git describe --tags --abbrev=0)

# 2. Spawn Explore agent (parallel with step 3-4)
# → "Find all CLI commands, config options, hidden flags, env vars in /tmp/[repo]-research"

# 3. GitHub activity
gh pr list -R [org]/[repo] --state merged --limit 30 --json title,mergedAt
gh issue list -R [org]/[repo] --label question --limit 20

# 4. Web search
# → "[tool] 2025" "[tool] 2026" "[tool] tutorial"

# 5. Synthesize → Output structure above

# 6. Cleanup
rm -rf /tmp/[repo]-research

---

Checklist

• [ ] Detect context: Check package.json/Cargo.toml/pyproject.toml for versions
• [ ] Clone repo to /tmp, checkout latest stable tag
• [ ] Explore agent: CLI commands, config schema, hidden flags, env vars
• [ ] GitHub: Recent merged PRs, issues tagged "question"/"documentation"
• [ ] Web search: "[tool] 2025", "[tool] 2026", skip pre-2025
• [ ] Synthesize: Commands table, config table, gotchas, patterns
• [ ] Cite sources: repo@commit, PR numbers, blog URLs
• [ ] Clean up: rm -rf /tmp/[repo]-research

---

Source Priority

1. Source code (actual behavior)
2. Recent PRs (features being added)
3. GitHub issues (real problems)
4. Blog posts 2025-2026 (practical patterns)
5. Official docs (baseline, often outdated)

Skip: Stack Overflow, anything pre-2025, basic tutorials

---

Top Mistakes

| Mistake | Fix | |---------|-----| | Using beta/canary | Checkout latest stable TAG, not main | | Old content (pre-2025) | Always add year to search queries | | Trusting docs over code | Code wins: check actual defaults in source | | Missing env vars | Search process.env, std::env, os.environ | | Forgetting cleanup | rm -rf /tmp/[repo]-research when done |

---

Key Searches

# Hidden/experimental flags
rg "hidden|experimental|unstable" /tmp/[repo]-research

# Environment variables by language
rg "process\.env\." /tmp/[repo]-research --type ts    # TypeScript
rg "std::env::" /tmp/[repo]-research --type rust      # Rust
rg "os\.environ" /tmp/[repo]-research --type py       # Python
rg "os\.Getenv" /tmp/[repo]-research --type go        # Go

# Recent changes
git log --oneline --since="2025-06-01" | head -30

---

Done When

• [ ] Have version number from stable tag
• [ ] Commands table has 5+ entries
• [ ] Config table covers main options
• [ ] Gotchas section has 3+ real issues from GitHub/code
• [ ] All sources cited with links

---

Decision Tree

What are you researching?
│
├─ CLI tool (wrangler, cargo, bun)
│  Focus: src/cli/, commands, flags, env vars
│
├─ Library/Framework (React, Next.js)
│  Focus: packages/*/src/, exported APIs, deprecations
│
├─ Runtime (Bun, Deno, Node)
│  Focus: built-ins, runtime flags, compat layers
│
└─ Database/Service (D1, R2, Postgres)
   Focus: query syntax, config, limits, gotchas

Key Searches by Type

| Type | Where to look | Key searches | |------|---------------|--------------| | CLI | src/cli/, bin/ | hidden.*true, #[arg(, process.env | | Library | packages/*/src/, index.ts | export , deprecated, experimental | | Runtime | src/, built-ins | flag, --, compat | | Database | queries, limits | limit, max, error |

Deep strategies: STRATEGIES.md

---

Subagent: Code Investigator

Investigate /tmp/[repo]-research for [TOOL].
Find: CLI commands, config options, hidden/experimental flags, env vars.
Check git log --oneline -30 for recent changes.
Output as markdown tables.

Use model: sonnet (balance of speed + depth)

---

Subagent: Web Researcher

Search "[TOOL] 2025" and "[TOOL] 2026".
Find 5-10 recent tutorials, blog posts, announcements.
Extract: patterns, gotchas, tips.
Skip: Stack Overflow, anything pre-2025, basic tutorials.

Use model: haiku (fast, web-focused)

---

References

| Need | File | |------|------| | Output templates by tool type | OUTPUT-TEMPLATES.md | | Example research sessions | EXAMPLES.md | | Tool-specific deep strategies | STRATEGIES.md |