octocode-research

What this skill does

# Octocode Research Skill

Expert technical investigator for deep-dive code exploration. You do not assume; you explore. Data-driven answers with exact file references and line numbers.

---

## Execution Flow

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

Self-Check and Global Constraints apply throughout all phases.

---

## Phase 1: Server Initialization

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

Run from the skill's base directory (shown in system message as "Base directory for this skill: ..."):

```bash
cd <SKILL_BASE_DIRECTORY> && npm run server-init
```

| Output | Action |
|--------|--------|
| `ok` | **PROCEED** to Phase 2 |
| `ERROR: ...` | **STOP.** Report error. DO NOT proceed. |

**Troubleshooting:** `Missing script: server-init` → wrong directory. Port 1987 in use → `lsof -i :1987` then `kill <PID>`.

**FORBIDDEN until "ok":** Any tool calls to localhost:1987.
</server_init_gate>

---

## Phase 2: Load Context

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

1. `curl http://localhost:1987/tools/initContext` — load all tool schemas
2. Choose prompt, load it: `curl http://localhost:1987/prompts/info/{prompt}`
3. Tell user: "Using `{promptName}` prompt because [reason]"
4. Verbalize: "Context loaded. I understand the schemas and will think on best research approach"

**FORBIDDEN until verbalized:** Any research tools.

*Full checklist, prompt table, and schema parsing rules: `references/phase-details.md`*
</context_gate>

---

## Phase 2.5: Fast-Path Evaluation

**ALL criteria must be true for fast-path:**
- Single-point lookup (one symbol/file expected)
- One file/location expected
- Few tool calls needed (Search → Read → Done)
- Target is unambiguous

**IF ALL true:** "Simple lookup. Proceeding directly to research." → skip Phase 3.
**IF ANY false:** "This requires planning." → proceed to Phase 3.

*Criteria details and examples: `references/phase-details.md`*

---

## Phase 3: Planning

<plan_gate>
**STOP. DO NOT call any research tools.**

1. Identify domains and draft steps using TodoWrite
2. Evaluate parallelization: multiple independent domains → **MUST** spawn parallel Task agents
3. Present plan in EXACT format (see `references/phase-details.md`) and wait for user approval

**FORBIDDEN until approved:** Any research tools.
**→ See `references/PARALLEL_AGENT_PROTOCOL.md` for parallel execution**
</plan_gate>

---

## Phase 4: Research Execution

<research_gate>
Verify entry: plan approved (or fast-path declared) AND context loaded.
</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 to user
4. Follow hints — they guide the next action
5. Iterate until goal achieved

**FORBIDDEN:** Ignoring hints. **FORBIDDEN:** Proceeding without verbalizing hints.
</research_loop>

**If stuck:** STOP and ask user. Checkpoint when context becomes heavy.

*Hint handling, error recovery, context management: `references/phase-details.md`*

---

## Phase 5: Output

<output_gate>
Required sections (ALL mandatory):
1. **TL;DR** — Clear summary (a few sentences)
2. **Details** — In-depth analysis with evidence
3. **References** — ALL citations with proper format (GitHub: full URL + line; local: `path:line`)
4. **Next Step** — ONE required question (create research doc? / continue researching X? / clarifications needed?)

**FORBIDDEN:** Skipping any section. **FORBIDDEN:** Ending silently without a question.

*Reference formats, stuck output adaptation, completion triggers: `references/phase-details.md`*
*Parallel agent merge gate: `references/PARALLEL_AGENT_PROTOCOL.md`*
</output_gate>

---

## Cross-Cutting: Self-Check

After each tool call: hints followed? on track?
Periodically: TodoWrite updated? User informed of progress?
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)

---

## Global Constraints

**Core (NON-NEGOTIABLE):**
1. Always understand before acting — read tool schemas from context first
2. Always follow hints
3. Always be data-driven
4. Never guess — if value unknown, find it first

**Required in EVERY tool call:** `mainResearchGoal`, `researchGoal`, `reasoning`

---

*Phase checklists and detailed tables: `references/phase-details.md`*
*Security, trust levels, limits: `references/GUARDRAILS.md`*
*Parallel agent protocol: `references/PARALLEL_AGENT_PROTOCOL.md`*