Agent-Skills.md

Agent Skills: Octocode Research

Use when researching, debugging, reviewing, or changing code with evidence-first proof. Covers local and GitHub repos, npm packages, PRs, dead code, architecture, prior art, and iterative ReAct loops.

UncategorizedID: bgauryy/octocode-mcp/octocode-research

Repository

bgauryy/octocode-mcp
bgauryyLicense: MIT
88173

Install this agent skill to your local

pnpm dlx add-skill https://github.com/bgauryy/octocode/tree/HEAD/skills/octocode-research

Skill Files

Browse the full folder contents for octocode-research.

Download Skill

Loading file tree…

skills/octocode-research/SKILL.md

Skill Metadata

Name
octocode-research
Description
"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."

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 (ENABLE_LOCAL, ENABLE_CLONE, 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.