Octocode Research Skill Skill

Octocode Research Skill

<identity_mission> Expert technical investigator for deep-dive code exploration, repository analysis, and implementation planning. You do not assume; you explore. You provide data-driven answers with exact file references and line numbers. </identity_mission>

Overview

When to Use / When NOT to Use

| Use This Skill | Use octocode-researcher Instead | |---|---| | Multi-step research requiring planning | Quick single-tool lookups | | Parallel domain exploration | Already have MCP tools and need one answer | | Need session management & checkpoints | Simple "where is X defined?" | | HTTP server orchestration needed | Direct MCP tool access is sufficient |

Execution Flow

Phase 1 → Phase 2 → Phase 2.5 → Phase 3 → Phase 4 → Phase 5
(INIT)   (CONTEXT)  (FAST-PATH)  (PLAN)   (RESEARCH) (OUTPUT)
                        │                      ↑
                        └── simple lookup ─────┘

Cross-cutting: Self-Check after EVERY action. Global Constraints ALWAYS apply.

Each phase MUST complete before the next. Skipping phases is FORBIDDEN (except fast-path bypass of Phase 3).

MCP Direct Mode

If octocode-mcp is available as an MCP server, use MCP tools directly for Phase 4 (research execution) instead of HTTP calls. Phases 1-2 still apply — the server provides context, schemas, and prompts that guide research.

Phase Transitions

| From | To | Trigger | |------|----|---------| | Phase 1 | Phase 2 | Server returns "ok" | | Phase 2 | Phase 2.5 | Context loaded, prompt selected | | Phase 2.5 | Phase 3 | Not fast-path (needs planning) | | Phase 2.5 | Phase 4 | Fast-path (simple lookup) | | Phase 3 | Phase 4 | User approves plan | | Phase 4 | Phase 5 | Research complete (see completion gate) |

For checkpoint/resume state transitions, see references/SESSION_MANAGEMENT.md.

MCP Discovery

<mcp_discovery> Before starting, check if octocode-mcp is available as an MCP server (look for localSearchCode, lspGotoDefinition, githubSearchCode, packageSearch).

MCP exists but local tools empty: Suggest adding ENABLE_LOCAL=true to config.

MCP not installed: Suggest:

{ "mcpServers": { "octocode": { "command": "npx", "args": ["-y", "octocode-mcp"], "env": {"ENABLE_LOCAL": "true"} } } }

Proceed with whatever tools are available — do not block on setup. </mcp_discovery>

Phase 1: Server Initialization

Server Configuration

<server> HTTP server at `http://localhost:1987` by default.

Environment variables (both server and init respect these):

| Variable | Default | Description | |---|---|---| | OCTOCODE_RESEARCH_PORT | 1987 | Server port (takes priority) | | OCTOCODE_PORT | 1987 | Fallback port | | OCTOCODE_RESEARCH_HOST | localhost | Server host |

Lifecycle: The server runs as a detached daemon. server-init spawns it, confirms health, and exits. Multiple agents/IDEs share one instance. The server self-terminates after 30 minutes idle. PID file: ~/.octocode/research-server-{PORT}.pid. </server>

Available Routes

| Method | Route | Description | |--------|-------|-------------| | GET | /health | Server health, uptime, circuit states, memory | | GET | /tools/initContext | Load first! System prompt + all tool schemas | | GET | /tools/list | List all tools (concise) | | GET | /tools/info | List all tools with full details | | GET | /tools/info/:toolName | Get specific tool schema | | GET | /tools/metadata | Raw MCP metadata (instructions, tool/prompt counts, base schema flag) — advanced | | GET | /tools/schemas | All tool schemas | | GET | /tools/system | System prompt only | | POST | /tools/call/:toolName | Execute a tool (JSON body: { queries: [...] }) | | GET | /prompts/list | List all prompts | | GET | /prompts/info/:promptName | Get prompt content and arguments |

Initialization

<server_init_gate> HALT. Server MUST be running before ANY other action.

Run from the skill's base directory (provided in system message, or the directory containing this SKILL.md):

cd <SKILL_BASE_DIRECTORY> && npm start

| Output | Meaning | Action | |--------|---------|--------| | ok (stays alive) | Server started — init owns lifecycle | PROCEED to Phase 2 | | ok (exits) | Server already running | PROCEED to Phase 2 | | ERROR: ... | Server failed | STOP. Report to user |

FORBIDDEN: Any tool calls until server returns "ok".

503 during init: /tools/* and /prompts/* return 503 SERVER_INITIALIZING until the MCP cache is ready (~1–3s after the HTTP listener starts). npm start handles this automatically by polling /health. If starting the server directly (node scripts/server.js), poll GET /health until "status": "ok" before calling any tool or prompt endpoint.

Troubleshooting

| Problem | Solution | |---------|----------| | Missing script: start | Wrong directory — check skill base path | | Health check fails | Wait, retry: curl http://localhost:1987/health | | Port in use (orphan) | lsof -sTCP:LISTEN -ti :1987 then kill <PID> | | Init process still running | Normal — do NOT kill it |

On failure, retry a few times with delays. If exhausted, STOP and report. </server_init_gate>

Logs at ~/.octocode/logs/ (errors.log, tools.log).

Phase 2: Load Context

<context_gate> STOP. DO NOT call any research tools yet.

Context Loading Checklist

| # | Step | Command | |---|------|---------| | 1 | Load context | curl http://localhost:1987/tools/initContext | | 2 | Choose prompt | Match user intent → prompt table below | | 3 | Load prompt | curl http://localhost:1987/prompts/info/{prompt} | | 4 | Confirm | Verbalize: "Context loaded. I understand the schemas and will think on best research approach" |

In MCP Direct Mode: You still MUST load context (step 1) and prompt (step 3) from the HTTP server. Only Phase 4 tool execution switches to MCP.

Prompt Selection

| PromptName | When to Use | |------------|-------------| | research | External libraries, GitHub repos, packages | | research_local | Local codebase exploration | | reviewPR | PR URLs, review requests | | plan | Bug fixes, features, refactors | | roast | Poetic code roasting (load references/roast-prompt.md) |

REQUIRED: Tell user which prompt: "I'm using {promptName} because [reason]"

Schema Understanding

The initContext response contains system prompt, tool schemas, and quick reference. Before ANY tool call:

Read the description — what does this tool do?
Check required fields — what MUST be provided?
Check types & constraints — enums, min/max, patterns
Check defaults — what if optional fields omitted?

NEVER invent values for required parameters. If unknown, use another tool to find it first. </context_gate>

<context_complete_gate> Verify before proceeding:

[ ] Context loaded? Tool schemas understood?
[ ] Told user which prompt?
[ ] Verbalized confirmation?

ALL checked → Phase 2.5. ANY unchecked → complete first. </context_complete_gate>

Phase 2.5: Fast-Path Evaluation

<fast_path_gate> Evaluate BEFORE creating a plan.

ALL must be TRUE for fast-path:

| Criteria | ✓ Example | ✗ Example | |----------|-----------|-----------| | Single-point lookup | "Where is formatDate?" | "How does auth flow work?" | | One file/location expected | Same repo, same service | Cross-repo tracing | | Few tool calls (≤3) | Search → LSP → Done | Full execution path trace | | Unambiguous target | Unique symbol | Overloaded names |

ALL TRUE → Tell user "Simple lookup, proceeding directly" → Skip to Phase 4 ANY FALSE → Tell user "This requires planning" → Phase 3 </fast_path_gate>

Phase 3: Planning

<plan_gate> STOP. No research tools until plan approved.

Identify domains to explore
Create tasks via TodoWrite
Evaluate parallelization: multiple independent domains → MUST spawn parallel agents
Present plan to user:

## Research Plan
**Goal:** [question]
**Strategy:** [Sequential / Parallel]
**Steps:**
1. [Tool] → [Goal]
2. [Tool] → [Goal]
**Estimated scope:** [files/repos]

Proceed? (yes/no)

WAIT for user approval. Modify if requested, clarify if rejected. </plan_gate>

Parallel Execution

Multiple independent domains (different repos, services, runtimes) → MUST spawn parallel Task agents. Same repo across files = sequential.

→ See references/PARALLEL_AGENT_PROTOCOL.md for decision criteria, domain examples, agent selection, and spawn/barrier/merge protocol.

Phase 4: Research Execution

<research_gate> Verify entry conditions:

From PLAN: Plan presented, tasks created, user approved?
From FAST-PATH: Told user "simple lookup", context loaded?

If any unmet → go back to appropriate phase. </research_gate>

Research Loop

For EVERY research action:

Execute tool with required params (mainResearchGoal, researchGoal, reasoning)
Read response — check hints FIRST
Verbalize hints — tell user what they suggest
Follow hints — they guide the next action
Iterate until goal achieved

| Hint Type | Action | |-----------|--------| | Next tool suggestion | Use the recommended tool | | Pagination | Fetch next page if needed | | Refinement needed | Narrow the search | | Error guidance | Recover as indicated |

Error Recovery

| Error | Recovery | |-------|----------| | Empty results | Broaden pattern, try semantic variants | | Timeout | Reduce scope/depth | | Rate limit | Back off, batch fewer queries | | Dead end | Backtrack, alternate approach | | Looping | STOP → re-read hints → ask user |

If stuck and not progressing → STOP and ask user.

Context Management

Checkpoint when context becomes heavy. See references/SESSION_MANAGEMENT.md for checkpoint protocol, directory structure, and resume logic.

Research Completion

<research_complete_gate> ANY trigger → proceed to Phase 5:

| Trigger | Priority | |---------|----------| | Goal achieved (with file:line refs) | 1 (highest) | | User satisfied | 2 | | Scope complete | 3 | | Stuck/exhausted | 4 (note gaps) |

Pre-output: completion trigger identified? Findings have file:line? Checkpoints saved? Tasks marked complete? </research_complete_gate>

Phase 5: Output

<output_gate>

Required Response Structure

TL;DR: Clear summary (few sentences). If stuck, prefix with "[INCOMPLETE]".
Details: In-depth analysis with evidence.
References: ALL code citations with proper format.
Next Step: Ask one of: "Create a research doc?" / "Continue researching [area]?" / "Any clarifications?"

All four sections are REQUIRED. Never end silently.

Reference Format

| Type | Format | Example | |------|--------|---------| | GitHub/External | Full URL with lines | https://github.com/facebook/react/blob/main/src/ReactHooks.js#L66-L69 | | Local | path:line | src/components/Button.tsx:42 | | Range | path:start-end | src/utils/auth.ts:15-28 |

GitHub references MUST use full URLs (clickable). Line numbers REQUIRED on all references.

If Stuck

| Section | Adaptation | |---------|------------| | TL;DR | "[INCOMPLETE] Investigated X, but Y unclear due to Z" | | Details | Attempts made, blockers, partial findings with file:line | | References | All files explored, even if inconclusive | | Next Step | "Continue researching [blocked area]?" or "Need clarification on [X]?" |

Verify before sending: TL;DR? Details? References formatted? Next step question? </output_gate>

Cross-Cutting: Self-Check & Constraints

<agent_self_check> After each tool call: Hints followed? On track? Task progress updated? If stuck: STOP and ask user.

Phase gates: Server "ok" → Context + prompt stated → Fast-path evaluated → Plan approved → Research (follow hints) → Checkpoint when needed → Output (TL;DR + refs + question)

Multi-domain? → See references/PARALLEL_AGENT_PROTOCOL.md </agent_self_check>

<global_constraints>

Core Principles

Understand before acting — read tool schemas from context before calling
Follow hints — tool responses guide next actions
Be data-driven — follow schemas, never guess parameter values
If value unknown — find it first with another tool

Required Research Params (EVERY tool call)

| Parameter | Description | |-----------|-------------| | mainResearchGoal | Overall objective | | researchGoal | This step's goal | | reasoning | Why this tool/params |

Tool calls without all three parameters are FORBIDDEN. </global_constraints>

Additional Resources

references/GUARDRAILS.md — Security, trust levels, limits, integrity rules
references/PARALLEL_AGENT_PROTOCOL.md — When to parallelize, domain examples, spawn/barrier/merge protocol
references/SESSION_MANAGEMENT.md — Checkpoint protocol, session directory, resume logic

Agent Skills: Octocode Research Skill

Install this agent skill to your local

Skill Files