/octocode-research
Use when a technical question or code change needs evidence before conclusions: find or locate behavior, explain systems, diagnose failures, review diffs, validate dependencies or prior art, prove dead code, plan refactors, or ship the smallest verified fix.
$ npx -y skills add bgauryy/octocode-mcp --skill octocode-research --agent claude-codeHow it fires
How this skill gets triggered: by you, by Claude, or both.
- Fires itselfAuto-invocation. Claude auto-loads it when your prompt matches the work.Auto-invocation is when the right skill fires by itself at the right moment, driven by a FLOW.md router and a hook, instead of you invoking it by name. It is the difference between a skill being installed and a skill actually getting used.Read the full definition →
- You can call itInvoke it directly when you want it.
- Slash command
/octocode-research
Context preview
The summary Claude sees to decide when to auto-load this skill.
Use when a technical question or code change needs evidence before conclusions: find or locate behavior, explain systems, diagnose failures, review diffs, validate dependencies or prior art, prove dead code, plan refactors, or ship the smallest verified fix.
SKILL.md
octocode-research.SKILL.mdname: octocode-research
description: "Use when a technical question or code change needs evidence before conclusions: find or locate behavior, explain systems, diagnose failures, review diffs, validate dependencies or prior art, prove dead code, plan refactors, or ship the smallest verified fix."
Octocode Research
Evidence-first technical work. Flow: `FRAME → CLASSIFY → MODEL → SEARCH → READ EXACT → PROVE → DECIDE/PATCH → VERIFY`. Modes: investigate, review, change, refactor, prior-art validation, and evidence loops. Task class (bug/feature/enhancement/unknown) is separate from mode.
Lobby rules
1. State corpus, observed/desired behavior, authority, task class, mode, and active/skipped surfaces. 2. Call it a bug only when evidence proves a supported contract was violated. 3. Root cause needs mechanism, trigger, violated contract, divergence boundary, and disconfirming or counterfactual proof. 4. Use the strongest available handle; for nontrivial claims inspect at least two of structure, stream, and connections. 5. Track `claim → evidence → confidence → next check`; cite exact anchors and checks that actually ran. 6. Ask before broad contracts, deletion/rename, thin evidence, or three unrelated search spaces; patch only after proof.
Smart routes — load only what the current step needs
- Start every task with `references/algorithm.md`, then `references/problem-framing.md` — choose evidence grade, class, proof, and success before searching.
- When choosing a workflow, load `references/workflows.md`; then use `references/workflow-local.md`, `references/workflow-external.md`, `references/workflow-debug.md`, `references/workflow-change.md`, or `references/workflow-refactor.md` — get the corpus/mode-specific gates without mixing flows.
- When reviewing a diff/PR, load `references/workflow-pr-review.md`; use `references/workflow-pr-review-analysis.md` during inspection and `references/workflow-pr-review-report.md` during reporting — separate evidence collection from verdict.
- When modes must combine, load `references/workflow-combination.md` — order dependent flows and keep one claim ledger.
- When investigating or changing code, load `references/code-research.md`; for broader validation load `references/research-flow.md` — choose code semantics or general-source proof deliberately.
- When planning progress or fan-out, load `references/researcher-mindset.md`; when evidence shifts, load `references/loop-mode.md` — budget checks and converge instead of searching indefinitely.
- When mapping ecosystems, load `references/github-landscape.md`; when a decision is deep or contested, load `references/long-research.md` — rank prior art or produce a durable brief.
- When command, MCP, or schema details matter, load `references/octocode.md` — use verified transport syntax; when improving this skill, prefer `octocode-graph-eval` (else `references/improve-loop.md`) — enforce an accept/revert gate.
Related routes
- Use `octocode-awareness` for shared-repo coordination, locks, verification, and durable lessons.
- Use `octocode-brainstorming` when worth-building is unresolved; `octocode-graph-eval` for goal→KPI / keep-discard; `octocode-rfc-generator` for design contracts; `octocode-skills` for skill-folder lifecycle.
- Use `octocode-subagent` for bounded fan-out; `octocode-roast` for critique tone.
Script and output
- When changing this skill, run `scripts/eval-research.mjs` for the matching case — catch routing regressions.
- Quick output: `Finding`, `Evidence`, `Confidence`, `Next`; decisions add verdict, risks, exact anchors, verification, and smallest safe fix.
Read more
name: octocode-research description: "Use when a technical question or code change needs evidence before conclusions: find or locate behavior, explain systems, diagnose failures, review diffs, validate dependencies or prior art, prove dead code, plan refactors, or ship the smallest verified fix."
Octocode Research
Evidence-first technical work. Flow: `FRAME → CLASSIFY → MODEL → SEARCH → READ EXACT → PROVE → DECIDE/PATCH → VERIFY`. Modes: investigate, review, change, refactor, prior-art validation, and evidence loops. Task class (bug/feature/enhancement/unknown) is separate from mode.
Lobby rules
1. State corpus, observed/desired behavior, authority, task class, mode, and active/skipped surfaces. 2. Call it a bug only when evidence proves a supported contract was violated. 3. Root cause needs mechanism, trigger, violated contract, divergence boundary, and disconfirming or counterfactual proof. 4. Use the strongest available handle; for nontrivial claims inspect at least two of structure, stream, and connections. 5. Track `claim → evidence → confidence → next check`; cite exact anchors and checks that actually ran. 6. Ask before broad contracts, deletion/rename, thin evidence, or three unrelated search spaces; patch only after proof.
Smart routes — load only what the current step needs
- Start every task with `references/algorithm.md`, then `references/problem-framing.md` — choose evidence grade, class, proof, and success before searching.
- When choosing a workflow, load `references/workflows.md`; then use `references/workflow-local.md`, `references/workflow-external.md`, `references/workflow-debug.md`, `references/workflow-change.md`, or `references/workflow-refactor.md` — get the corpus/mode-specific gates without mixing flows.
- When reviewing a diff/PR, load `references/workflow-pr-review.md`; use `references/workflow-pr-review-analysis.md` during inspection and `references/workflow-pr-review-report.md` during reporting — separate evidence collection from verdict.
- When modes must combine, load `references/workflow-combination.md` — order dependent flows and keep one claim ledger.
- When investigating or changing code, load `references/code-research.md`; for broader validation load `references/research-flow.md` — choose code semantics or general-source proof deliberately.
- When planning progress or fan-out, load `references/researcher-mindset.md`; when evidence shifts, load `references/loop-mode.md` — budget checks and converge instead of searching indefinitely.
- When mapping ecosystems, load `references/github-landscape.md`; when a decision is deep or contested, load `references/long-research.md` — rank prior art or produce a durable brief.
- When command, MCP, or schema details matter, load `references/octocode.md` — use verified transport syntax; when improving this skill, prefer `octocode-graph-eval` (else `references/improve-loop.md`) — enforce an accept/revert gate.
Related routes
- Use `octocode-awareness` for shared-repo coordination, locks, verification, and durable lessons.
- Use `octocode-brainstorming` when worth-building is unresolved; `octocode-graph-eval` for goal→KPI / keep-discard; `octocode-rfc-generator` for design contracts; `octocode-skills` for skill-folder lifecycle.
- Use `octocode-subagent` for bounded fan-out; `octocode-roast` for critique tone.
Script and output
- When changing this skill, run `scripts/eval-research.mjs` for the matching case — catch routing regressions.
- Quick output: `Finding`, `Evidence`, `Confidence`, `Next`; decisions add verdict, risks, exact anchors, verification, and smallest safe fix.
Evidence-first code research for AI agents and developers. Octocode researches your local code and external code alike (GitHub repos, PRs, npm) with one toolset: ripgrep + AST search, trees, precise reads, and LSP.
Repo: bgauryy/octocode-mcp
Other skills on octocode.
- /octocode-benchmark
Use when planning, running, grading, or reporting the by-hand Octocode research benchmark — pairwise matchups (Octocode anchor vs one baseline: gh+RTK, gh+Headroom, or plain gh) over markdown questions, with a fresh isolated runner agent per (question, arm, pass), one blind
Open skill - /octocode-awareness
Use when coordinating work in a shared repo — multi-agent or solo across sessions: collision avoidance, handoffs, verification debt, durable memory/wiki, hooks setup/debug, and repo learning before planning, editing, reviewing, or testing.
Open skill - /octocode-brainstorming
Use when an idea needs disciplined exploration before building: generate options, test worth-building, map adjacent solutions, challenge assumptions, narrow scope, or choose Build RFC / Prototype / Narrow / Park — even without saying brainstorm.
Open skill - /octocode-chrome-devtools
Use when browser debugging, scraping a known URL efficiently, or running a multi-step page workflow needs real Chrome DevTools evidence: network, console, performance, DOM/CSS, screenshots/PDF, security, cookies/storage, click/fill/search flows, or auth-gated live pages via CDP
Open skill - /octocode-documentation
Use when writing or updating docs: README, API docs, runbooks, AGENTS.md, CLAUDE.md, ADRs, Diátaxis restructuring, or codebase documentation for humans or coding agents.
Open skill - /octocode-graph-eval
Use when measuring whether a change helped or looping until a target metric is hit — for one agent loop or a graph of loops (multi-agent workflow): ACCEPT/REVERT, keep/discard, goal→KPI contracts, eval suites, graders, held-out checks, benchmarks, TDD failing-case-first,
Open skill