Octocode Research Skill

Overview

Execution Flow

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

Phase Transitions

State Transitions

Phase 1: Server Initialization

Server Configuration

Available Routes

/tools/initContext

/prompts/info/:promptName

/tools/call/:toolName

Initialization Process

Required Action

cd <SKILL_BASE_DIRECTORY> && npm run server-init

Base directory for this skill: /path/to/skill

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

Output Interpretation

ok

ERROR: ...

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

Missing script: server-init

curl http://localhost:1987/health

lsof -i :1987

kill <PID>

Retry Policy

Server Maintenance

~/.octocode/logs/

Phase 2: Load Context

Pre-Conditions

• Server returned "ok" in Phase 1

Context Loading Checklist (MANDATORY - Complete ALL steps)

curl http://localhost:1987/tools/initContext

{prompt}

curl http://localhost:1987/prompts/info/{prompt}

FORBIDDEN Until Context Loaded

• Any research tools

ALLOWED During Context Loading

• curl

  commands to localhost:1987
• Text output to user
• Reading tool schemas </context_gate>

Understanding Tool Schemas

initContext

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

• NEVER invent values for required parameters
• NEVER use placeholders or guessed values
• IF required value unknown → THEN use another tool to find it first </parameter_rules>

Verification (REQUIRED)

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

Prompt Selection

research

research_local

reviewPR

plan

roast

references/roast-prompt.md

"I'm using the

{promptName}

prompt because [reason]"

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

Phase 2.5: Fast-Path Evaluation

Fast-Path Decision

Criteria (ALL must be TRUE for fast-path)

Decision Logic

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

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

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

STOP. DO NOT call any research tools.

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 TodoWrite tool.
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 Until Plan Approved

• Any research tools

ALLOWED During Planning

• TodoWrite

  (to draft plan)

• AskUserQuestion

  (to confirm)
• Text output (to present plan)

Gate Verification

• Plan created in

  TodoWrite

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

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

Domain Classification

Classification Examples

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

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

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

Agent Selection

Explore

opus

Explore

haiku

Parallel Agent Protocol

references/PARALLEL_AGENT_PROTOCOL.md

Phase 4: Research Execution

STOP. Verify entry conditions.

IF Coming from PLAN Phase:

• Plan presented to user?

• TodoWrite

  completed?
• Parallel strategy evaluated?
• User approved the plan?

IF Coming from FAST-PATH:

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

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

Hint Handling

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. </thought_process>

Error Recovery

Context Management

.octocode/research/{session-id}/checkpoint-{N}.md

Checkpoint Content

Session Files

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

Resume

session.json

What to Keep/Discard After Checkpoint

Research Completion

Completion Triggers (ANY one triggers OUTPUT)

Trigger Precedence (if multiple fire simultaneously)

Pre-Output Checklist

• Completion trigger identified?
• Key findings have file:line references?
• Checkpoints saved if research was extensive?
• TodoWrite items marked complete?

Phase 5: Output

STOP. Verify entry conditions and ensure output quality.

Entry Verification (from Phase 4)

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

• All domain-*.md files read and incorporated?
• Merge gate completed? (see

  references/PARALLEL_AGENT_PROTOCOL.md

  )
• Conflicts resolved or user acknowledged?

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).

IF Research is STUCK (goal not achieved)

auth/middleware.ts:42

auth/jwt.ts:88-120

Reference Format (MUST follow EXACTLY)

https://github.com/facebook/react/blob/main/packages/react/src/ReactHooks.js#L66-L69

path:line

src/components/Button.tsx:42

src/utils/auth.ts:15-28

Next Step Question (MANDATORY)

• "Create a research doc?" (Save to

  .octocode/research/{session}/research.md

  )
• "Continue researching [specific area]?"
• "Any clarifications needed?"

Gate Verification

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

Cross-Cutting: Self-Check

references/PARALLEL_AGENT_PROTOCOL.md

Reference: Global Constraints

Core Principles (NON-NEGOTIABLE)

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)

mainResearchGoal

researchGoal

reasoning

Execution Rules

Output Standards

Additional Resources

• references/GUARDRAILS.md

  - Security, trust levels, limits, and integrity rules