Octocode Research

Octocode Research Skill

Overview

Execution Flow

CRITICAL: Complete phases 1-5 in order. Self-Check and Constraints apply throughout.

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

CROSS-CUTTING (apply during all phases):
├── Self-Check Protocol - Run after EVERY action
└── Global Constraints - ALWAYS apply

MCP Direct Mode

If you already have octocode-mcp installed as an MCP server, use the octocode MCP tools directly for research execution (Phase 4) instead of calling tools via HTTP. The server initialization and context loading phases (1-2) still apply — the server provides essential research context and intent.

Phase Transitions

State Transitions

CRITICAL REMINDER: Run Self-Check after each action to verify you're on track.

Each phase MUST complete before proceeding to the next. FORBIDDEN: Skipping phases without explicit fast-path qualification.

Phase 1: Server Initialization

Server Configuration

Available Routes

Initialization Process

Required Action

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

cd <SKILL_BASE_DIRECTORY> && npm run server-init

Example: If system message says Base directory for this skill: /path/to/skill, run:

cd /path/to/skill && npm run server-init

Output Interpretation

The script handles health checks, startup, and waiting automatically with mutex lock.

FORBIDDEN Until Server Returns "ok"

• Any tool calls to localhost:1987 or research tools

ALLOWED Before Server Ready

• Checking "Base directory for this skill" in system message
• Running server-init command
• Troubleshooting commands (lsof, kill)

Troubleshooting

Retry Policy

On failure, retry a few times with reasonable delays. If retries are exhausted, STOP and report to user.

FORBIDDEN: Retrying indefinitely without timeout. FORBIDDEN: Proceeding after retries exhausted.

→ PROCEED TO PHASE 2 ONLY AFTER SERVER RETURNS "ok"

Server Maintenance

Phase 2: Load Context

Pre-Conditions

• Server returned "ok" in Phase 1

Context Loading Checklist (MANDATORY - Complete ALL steps)

FORBIDDEN Until Context Loaded

• Any research tools

ALLOWED During Context Loading

• curl commands to localhost:1987
• Text output to user
• Reading tool schemas

Understanding Tool Schemas

The initContext response contains everything you need:

1. System prompt - Overall guidance and constraints
2. Tool schemas - Required params, types, constraints, descriptions
3. Quick reference - Decision patterns for common scenarios

Schema Parsing (MUST do before ANY tool call)

1. Read the description - What does this tool ACTUALLY do?
2. Check required fields - What MUST be provided? (missing = error)
3. Check types & constraints - enums, min/max, patterns
4. Check defaults - What happens if optional fields omitted?

Parameter Discipline

Verification (REQUIRED)

After loading, you MUST verbalize:

"Context loaded. I understand the schemas and will think on best research approach"

FORBIDDEN: Proceeding without this verbalization.

Prompt Selection

REQUIRED: You MUST tell user which prompt you're using:

"I'm using the {promptName} prompt because [reason]"

FORBIDDEN: Proceeding to next phase without stating the prompt.

• Context loaded successfully?
• Tool schemas understood?
• Told user which prompt you're using?
• Verbalized: "Context loaded. I understand the schemas..."?

IF ANY checkbox is unchecked → STOP. Complete missing items. IF ALL checkboxes checked → PROCEED to Phase 2.5 (Fast-Path Evaluation)

Phase 2.5: Fast-Path Evaluation

CRITICAL: Evaluate BEFORE creating a plan. This saves time for simple queries.

Fast-Path Decision

Criteria (ALL must be TRUE for fast-path)

Decision Logic

IF ALL criteria are TRUE:

1. Tell user: "This is a simple lookup. Proceeding directly to research."
2. SKIP Phase 3 (Planning)
3. GO TO Phase 4 (Research) - skip research_gate pre-conditions

IF ANY criterion is FALSE:

1. Tell user: "This requires planning. Creating research plan..."
2. PROCEED to Phase 3 (Planning)

Examples

Qualifies for Fast-Path (ALL criteria TRUE)

• "Where is formatDate defined in this repo?" → Search → LSP goto → Done
• "What does the validateEmail function do?" → Search → Read → Done
• "Show me the User model" → Search → Read → Done

Requires Full Planning (ANY criterion FALSE)

• "How does React useState flow work?" → Needs PLAN (traces multiple files)
• "How does authentication flow work?" → Needs PLAN (multi-file)
• "Compare React vs Vue state management" → Needs PLAN (multiple domains)

Phase 3: Planning

Pre-Conditions

• Context loaded (/tools/initContext)
• User intent identified
• Fast-path evaluated (criteria checked)

Required Actions (MUST complete ALL)

1. Identify Domains: List research areas/files to explore.
2. Draft Steps: Create a structured plan with clear milestones. REQUIRED: Use your TaskCreate tool (or runtime equivalent, e.g., TodoWrite).
3. Evaluate Parallelization:
   • IF multiple independent domains → MUST spawn parallel Task agents.
   • IF single domain → Sequential execution.
4. Share Plan: Present the plan to the user in this EXACT format:

## Research Plan
**Goal:** [User's question]
**Strategy:** [Sequential / Parallel]
**Steps:**
1. [Tool] → [Specific Goal]
2. [Tool] → [Specific Goal]
...
**Estimated scope:** [files/repos to explore]

Proceed? (yes/no)

FORBIDDEN: Deviating from this format.

FORBIDDEN Until Plan Approved

• Any research tools

ALLOWED During Planning

• TaskCreate/TaskUpdate (or runtime equivalent, e.g., TodoWrite)
• AskUserQuestion (to confirm)
• Text output (to present plan)

Gate Verification

HALT. Verify before proceeding:

• Plan tasks created via TaskCreate?
• Plan presented to user in EXACT format above?
• Parallelization strategy selected?
• User approval obtained? (said "yes", "go", "proceed", or similar)

WAIT for user response. DO NOT proceed without explicit approval.

IF user approves → PROCEED to Phase 4 (Research) IF user requests changes → Modify plan and re-present IF user rejects → Ask for clarification

Parallel Execution Decision

Task(subagent_type="Explore", model="opus", prompt="Domain A: [goal]")
Task(subagent_type="Explore", model="opus", prompt="Domain B: [goal]")
→ Merge findings

FORBIDDEN: Sequential execution when multiple independent domains are identified.

Domain Classification

Classification Examples

Parallel (multiple domains):

"Compare how React and Vue handle state" → Domain A: React state (facebook/react) → Domain B: Vue state (vuejs/vue)

Sequential (single domain):

"How does React useState flow from export to reconciler?" → Same repo (facebook/react), tracing through files → Files are connected, not independent

Parallel (multiple domains):

"How does our auth service communicate with the user service?" → Domain A: auth-service repo → Domain B: user-service repo

Agent Selection

Agent capabilities are defined by the tools loaded in context.

Parallel Agent Protocol

→ See references/PARALLEL_AGENT_PROTOCOL.md

Phase 4: Research Execution

IF Coming from PLAN Phase:

• Plan presented to user?
• Tasks created and tracked?
• Parallel strategy evaluated?
• User approved the plan?

IF Coming from FAST-PATH:

• Told user "simple lookup, proceeding directly"?
• Context was loaded?

IF ANY pre-condition not met → STOP. Go back to appropriate phase. IF ALL pre-conditions met → PROCEED with research.

The Research Loop

1. Execute Tool with required research params (see Global Constraints)
2. Read Response - check hints FIRST
3. Verbalize Hints - tell user what hints suggest
4. Follow Hints - they guide the next tool/action
5. Iterate until goal achieved

FORBIDDEN: Ignoring hints in tool responses. FORBIDDEN: Proceeding without verbalizing hints.

Hint Handling

FORBIDDEN: Ignoring hints. FORBIDDEN: Using a different tool than hints suggest (unless you explain why).

Thought Process

• Stop & Understand: Clearly identify user intent. IF unclear → STOP and ASK.
• Think Before Acting: Verify context (what do I know? what is missing?). Does this step serve the mainResearchGoal?
• Plan: Think through steps thoroughly. Understand tool connections.
• Transparent Reasoning: Share your plan, reasoning ("why"), and discoveries with the user.
• Adherence: Follow prompt instructions. Include required research params (see Global Constraints).
• Data-driven: Follow tool schemas and hints (see Phase 2 Parameter Rules).
• Stuck or Unsure?: IF looping, hitting dead ends, or path is ambiguous → STOP and ASK the user.

Error Recovery

CRITICAL: IF stuck and not making progress → STOP and ask user for guidance.

Context Management

Checkpoint Content

Save: goal, key findings (file:line), open questions, next steps. Tell user: "Created checkpoint."

Session Files

.octocode/research/{session-id}/
├── session.json    # {id, state, mainResearchGoal}
├── checkpoint-*.md # Checkpoints
├── domain-*.md     # Parallel agent outputs
└── research.md     # Final output

Resume

If session.json exists with state ≠ DONE → Ask user: "Resume from last checkpoint?" → Yes: load & continue, No: fresh start.

What to Keep/Discard After Checkpoint

Research Completion

Completion Triggers (ANY one triggers OUTPUT)

Trigger Precedence (if multiple fire simultaneously)

FORBIDDEN: Ending research arbitrarily without a trigger. FORBIDDEN: Proceeding to OUTPUT without file:line evidence.

Pre-Output Checklist

• Completion trigger identified?
• Key findings have file:line references?
• Checkpoints saved if research was extensive?
• Tasks marked complete via TaskUpdate (or TodoWrite)?

IF ALL checked → PROCEED to Phase 5 (OUTPUT) IF ANY unchecked → Complete missing items first

Phase 5: Output

Entry Verification (from Phase 4)

• Completion trigger met? (goal achieved / stuck / user satisfied / scope complete)
• Key findings documented with file:line refs?
• Tasks updated via TaskUpdate (or TodoWrite)?

IF parallel agents were spawned:

• All domain-*.md files read and incorporated?
• Merge gate completed? (see references/PARALLEL_AGENT_PROTOCOL.md)
• Conflicts resolved or user acknowledged?

IF ANY entry condition not met → RETURN to Phase 4 (Research) or complete merge.

Required Response Structure (MANDATORY - Include ALL sections)

1. TL;DR: Clear summary (a few sentences).
2. Details: In-depth analysis with evidence.
3. References: ALL code citations with proper format (see below).
4. Next Step: REQUIRED question (see below).

FORBIDDEN: Skipping any section. TL;DR, Details, References, and Next Step are always required.

IF Research is STUCK (goal not achieved)

When entering Phase 5 via "Stuck (exhausted)" trigger, adapt output format:

Example Stuck TL;DR: "[INCOMPLETE] Traced authentication flow to auth/middleware.ts:42, but token validation logic at auth/jwt.ts:88-120 uses external service not accessible."

Reference Format (MUST follow EXACTLY)

Why full GitHub URLs? Users can click to navigate directly. Partial paths are ambiguous across branches/forks.

FORBIDDEN: Relative GitHub paths without full URL. FORBIDDEN: Missing line numbers in references.

Next Step Question (MANDATORY)

You MUST end the session by asking ONE of these:

• "Create a research doc?" (Save to .octocode/research/{session}/research.md)
• "Continue researching [specific area]?"
• "Any clarifications needed?"

FORBIDDEN: Ending silently without a question. FORBIDDEN: Ending with just "Let me know if you need anything else."

Gate Verification

HALT. Before sending output, verify:

• TL;DR included?
• Details with evidence included?
• ALL references have proper format?
• Next step question included?

IF ANY checkbox unchecked → Add the missing element before sending.

Cross-Cutting: Self-Check

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

Reference: Global Constraints

1. ALWAYS understand before acting - Read tool schemas from context before calling
2. ALWAYS follow hints - See Phase 4 for hint handling protocol
3. ALWAYS be data-driven - Let data guide you (see Phase 2 Parameter Rules)
4. NEVER guess - If value unknown, find it first with another tool

Research Params (REQUIRED in EVERY tool call)

FORBIDDEN: Tool calls without these three parameters.

Execution Rules

See Phase 3 for parallel execution strategy.

Output Standards

See Phase 5 (Output Gate) for reference formats.

Additional Resources

• references/GUARDRAILS.md - Security, trust levels, limits, and integrity rules