---

name: octocode-research description: Code research for external (GitHub) and local code exploration. Initiate when user wants to research some code or implementation or finding docs anywhere

Octocode Research Skill

HTTP API server for code research at http://localhost:1987

---

How to Use This Skill

Before starting research, read the relevant guides:

When using specific endpoints, consult the endpoint reference for parameters and examples:

• Each endpoint has a dedicated doc in ./references/ with HTTP examples and response structure

The reference docs explain:

• Which tools to use for which questions (task classification)
• Required workflows (e.g., search → get lineHint → LSP tools)
• Common mistakes to avoid
• How to present findings based on question complexity

---

CRITICAL: Always Check Server Health First

BEFORE making ANY API request, you MUST verify the server is running:

Why this matters: The server runs locally and may not be started. Making API calls without checking health first will result in connection errors (exit code 7).

---

LSP + Local Tools Coordination (CRITICAL)

<critical-coordination> **THE GOLDEN RULE**: Search first → Get lineHint → Then LSP

NEVER:

• Call LSP tools without lineHint from search
• Use /lsp/calls for types/variables (use /lsp/references instead)
• Read files to understand flow (use /lsp/calls)

Full guide: lsp_local_coordination.md </critical-coordination>

---

Available Endpoints

Base URL: http://localhost:1987

Local Tools

LSP Tools (Semantic)

GitHub Tools

Package Tools

---

Decision Tree

<decision-tree> <condition test="Is it LOCAL codebase?"> <yes>Use /local/* + /lsp/* tools <condition test="Flow question?"> <yes>/lsp/calls REQUIRED - see research_local_prompt.md</yes> </condition> </yes> <no>Use /github/* or /package/* - see research_external_prompt.md</no> </condition> </decision-tree>

---

Research Flows

Local: DISCOVER → EXECUTE → VERIFY → OUTPUT

External: PREPARE → DISCOVER → ANALYZE → OUTPUT

Detailed guides: Local | External

---

Critical Rules

<critical-rules> <rule id="thinking"> **IMPORTANT!** Always show your thinking and reasoning steps during research. Explain what you're looking for, why you chose specific tools/endpoints, and how findings connect to the research goal. </rule> <rule id="health-check"> **Health check FIRST** - Server may not be running. Check /health before ANY request. </rule> <rule id="linehint"> **Search first → get lineHint → LSP** - LSP tools need accurate line numbers from search results. </rule> <rule id="flow-tracing"> **Use /lsp/calls for flow tracing** - File reading alone misses call relationships. </rule> <rule id="parallel"> **Parallel calls for speed** - Server handles concurrent requests (3x faster). </rule> <rule id="no-guessing"> **Never guess line numbers** - Always get lineHint from search results. </rule> </critical-rules>

---

Required Parameters

All endpoints require research context:

---

Integration Patterns

Full guide: Task Integration

---

Output Protocol

Adaptive output based on question complexity:

Quality bar (all research):

• Fact-based: Every claim backed by actual code
• Evidence-linked: Path + line number for every finding
• Verified: Cross-referenced where possible

Complex research: Use multi-agent orchestration (spawn parallel Tasks)

Full guide: Output Protocol

---

Logging

Logs: ~/.octocode/logs/

---

Quick Example

Question: "How does authentication work?"

---

Best Practices

<best-practices> <do> - **Search first** → get `lineHint` → then LSP tools - **Use `/lsp/calls`** for flow/trace questions - **Run parallel calls** for independent queries - **Use `mode=discovery`** for fast initial file discovery - **Use `matchString`** for large files instead of `fullContent` - **Use `depth=1`** for call hierarchy, chain manually - **Start `/github/structure` at root** with `depth=1`, drill into subdirs </do> <dont> - Don't read files to understand flow → Use `/lsp/calls` - Don't guess line numbers → Always search first - Don't use `/lsp/calls` on types/variables → Use `/lsp/references` - Don't use `fullContent=true` on large files - Don't combine too many filters in `/github/search` </dont> </best-practices>

---

Error Recovery

<error-recovery> <error type="server-not-running"> <symptom>Connection refused, exit code 7</symptom> <solution>Check /health first, run `./install.sh start`</solution> </error> <error type="symbol-not-found"> <symptom>Symbol not found in LSP response</symptom> <solution>Use `/local/search` to find correct line number</solution> </error> <error type="empty-result"> <symptom>Empty result set from search</symptom> <solution>Try semantic variants (auth→login→credentials→session)</solution> </error> <error type="too-many-results"> <symptom>Result set too large to process</symptom> <solution>Add filters (`path`, `type`, `excludeDir`, `owner`/`repo`)</solution> </error> <error type="file-too-large"> <symptom>FILE_TOO_LARGE error</symptom> <solution>Use `matchString` or `startLine`/`endLine`</solution> </error> <error type="lsp-timeout"> <symptom>LSP timeout on deep call hierarchy</symptom> <solution>Reduce `depth`, chain manually with `depth=1`</solution> </error> <error type="lsp-fails"> <symptom>LSP returns error or empty</symptom> <solution>Fall back to `/local/search` results</solution> </error> <error type="rate-limited"> <symptom>Rate limit exceeded (GitHub API)</symptom> <solution>Reduce batch size, wait</solution> </error> <error type="blocked"> <symptom>Research blocked, no progress</symptom> <solution>Summarize attempts and ask user</solution> </error> </error-recovery>

---

Reference Guides

Technical Documentation