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