SkillsAdd

bgauryy/octocode

octocode-research

Use when code must be checked, not assumed: trace connections (callers, imports, cross-repo wiring, what breaks if I change it), locate behavior, map a system, diagnose a failure, RCA. Also for external repositories, npm packages, upstream/prior art, and general research. Plan a coding flow before writing, validate it after. Triggers on 'research this' or 'use octocode'. Gives exact file:line/PR/commit evidence with confidence. Skip trivial edits whose blast radius is already known. Not for aut…

First seen Jan 22, 2026

Installation

$ npx skills add bgauryy/octocode --skill octocode-research
View on skills.sh ↗ GitHub repository ↗

Summary

  • Use when code must be checked, not assumed: trace connections (callers, imports, cross-repo wiring, what breaks if I change it), locate behavior, map a system, diagnose a failure, RCA.
  • Also for external repositories, npm packages, upstream/prior art, and general research.
  • Plan a coding flow before writing, validate it after.
  • Triggers on 'research this' or 'use octocode'.
  • Gives exact file:line/PR/commit evidence with confidence.
  • Skip trivial edits whose blast radius is already known.
  • Not for authoring or copyediting the docs themselves, or for building skill folders: docs deliverable → octocode-documentation; SKILL.md folders → octocode-skills.

Similar popular skills

Related neighbors and high-traction skills in the same topics — useful to compare before installing.

azure-rbac Shared topics
microsoft/azure-skills 489K installs

Also in this package

Other skills from bgauryy/octocode · top by installs.

npx skills add bgauryy/octocode
octocode-prompt-optimizer 81 octocode-roast 74 octocode-documentation-writer 69 octocode-pull-request-reviewer 68 octocode-plan 54 octocode-brainstorming 30 octocode-engineer 28 octocode-rfc-generator 27 octocode-local-search 27 octocode-researcher 24

Browse all from bgauryy/octocode

More details

Agent compatibility

Declared targets from SKILL.md / docs. Unmarked agents are not listed — the skill may still install via the CLI.

Claude Code Not declared
Cursor Not declared
Codex Not declared
GitHub Copilot Not declared
Windsurf Not declared
Gemini CLI Not declared
Cline Not declared
OpenCode Not declared

Repository health

Stars 924
License LICENSE
Default branch main
Open issues 1
Status Active

Package contents

Files included with this skill beyond the listing page.

  • skill md SKILL.md 5,943 B
  • docs README.md 3,633 B
  • docs SUMMARY.md 4,006 B

History

  1. First seen on skills.sh
  2. First recorded snapshot · 273 installs

SKILL.md

Octocode Research

Evidence before assertion. Find the anchor, read the exact bytes, prove the claim, then answer or patch.

FRAME → CLASSIFY → MODEL → SEARCH → READ EXACT → PROVE → DECIDE/PATCH → VERIFY

That's the full shape, not a checklist to march through. Scale it to the claim: a small lookup gets a cheap read and an honest confidence label; a delete, a merge verdict, or a root cause earns the whole ladder. Skip stages you can already answer — but say which ones you skipped.

The rules

  1. Open with one line: corpus, actual vs desired, task class, mode, surfaces used and skipped.
  2. Call it a bug only when evidence shows a supported contract was violated.
  3. Root cause needs mechanism, trigger, violated contract, divergence boundary, and a killed alternate.
  4. Use the strongest handle you already hold. For nontrivial claims check two of: structure, stream, connections.
  5. A snippet is a lead. Empty means this lane can't see it, not it isn't there. Say which you mean.
  6. Track claim → evidence → confidence → next check. Cite exact anchors, and only checks that actually ran.
  7. Ask before broad contracts, deletes/renames, thin evidence, or a third unrelated search space. Patch after proof.

Stop when: grounded evidence answers the framed question and the alternate is dead; no cheap next step can change the conclusion; the budget is hit (default 3-5 decisive iterations or ~15 minutes); the last iterations changed no state; retries stay thin, or a license/product/architecture call belongs to the user; a gate blocks (broad contract, delete/rename, clone or run untrusted code, unapproved artifact write); or a skill edit measured flat/worse — revert through references/improve-loop.md. Report the remaining gaps instead of padding certainty.

Workflows

Start with references/algorithm.md (routing, evidence grades) and references/problem-framing.md (is this a bug, feature, enhancement, or still unknown?). Then pick one route by what you're looking at — load references/workflows.md when you need the per-route detail, the load budget per task size, or the handoff receipt between routes:

Situation Route
This repo, checkout, installed dependency references/workflow-local.md
External repository, npm package, upstream project references/workflow-external.md
Cross-repo connections, local clue → upstream, or remote code needing AST/LSP proof references/workflow-combination.md
Rank an ecosystem — several candidate repos/packages references/github-landscape.md
Something fails and you need the cause references/workflow-debug.md
Plan a coding flow, implement, migrate, patch behavior references/workflow-change.md
Reshape structure or names, keep behavior references/workflow-refactor.md
Validate after a change; review a PR or local diff references/workflow-pr-review.md
Trace connections — callers, imports, references, reachability references/code-research.md

Proof depth for any of them: references/code-research.md. General research — Map / Validate / Investigate / Plan across code, packages, docs, and history: references/research-flow.md.

Review runs in three parts: use references/workflow-pr-review.md for target, guidelines, and risk sizing; then references/workflow-pr-review-analysis.md for sizing depth, flow proof, and finding shape; then references/workflow-pr-review-report.md for the verification-gated recommendation and the optional written document.

Reach for these only when they earn it: references/loop-mode.md (evidence keeps flipping), references/long-research.md (durable decision brief), references/researcher-mindset.md (budgets, fan-out, campaign planning).

Load a reference when the current step needs it. Loading all of them is a failure mode.

Tooling

Prefer Octocode MCP tools when exposed. Otherwise npx octocode tools <name> — same 15 tools, same schemas, no loss.

npx octocode context --minimal                         # what's available
npx octocode tools <name> --scheme --json --compact    # read fields — never guess
npx octocode tools <name> --queries '<json>' --compact # run it

Batch up to five queries per call. Orient cheap (tree, discovery) before exact reads. Follow returned next.* and cursors instead of re-deriving them.

Read references/octocode.md when transport, tool choice, auth, gates (ENABLELOCAL, ENABLECLONE, ENABLE_RELEASES), materialization, diagnostics, or exit codes are unclear.

Output

Finding · Evidence · Confidence · Next. Decisions add verdict, risks, exact anchors, verification, and the smallest safe fix. Report gaps instead of padding certainty.

Related

octocode-brainstorming (worth building?) · octocode-rfc-generator (design contract) · octocode-graph-eval (goal→KPI) · octocode-documentation (docs deliverable) · octocode-skills (skill folders) · octocode-subagent (fan-out) · octocode-roast (critique tone).

When changing this skill, run node scripts/check-description.mjs (description contract; --help for flags) and gate accept/revert with references/improve-loop.md.