octocode-research - Claude MCP 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`](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:
  ```json
  { "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):

```bash
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:
1. Read the description — what does this tool do?
2. Check required fields — what MUST be provided?
3. Check types & constraints — enums, min/max, patterns
4. 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.**

1. **Identify domains** to explore
2. **Create tasks** via `TodoWrite`
3. **Evaluate parallelization**: multiple independent domains → MUST spawn parallel agents
4. **Present plan** to user:

```markdown
## 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`](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:
1. **Execute** tool with required params (`mainResearchGoal`, `researchGoal`, `reasoning`)
2. **Read response** — check `hints` FIRST
3. **Verbalize hints** — tell user what they suggest
4. **Follow hints** — they guide the next action
5. **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`](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

1. **TL;DR**: Clear summary (few sentences). If stuck, prefix with "[INCOMPLETE]".
2. **Details**: In-depth analysis with evidence.
3. **References**: ALL code citations with proper format.
4. **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

1. **Understand before acting** — read tool schemas from context before calling
2. **Follow hints** — tool responses guide next actions
3. **Be data-driven** — follow schemas, never guess parameter values
4. **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