octocode-research

What this skill does

# 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 paralle