octocode-loop

Octocode Loop

Run grounded research loops — Act → Observe → Learn → Repeat — where every step is proven by a real Octocode tool result, never guessed. Use this when the goal and the research path are already clear and the work is iterative: issue a call, read the result, adjust, repeat until evidence converges or a budget is hit. This file is the router; mechanics live in references/.

Core principle: an agent steered by concrete tool feedback beats one running open-loop. So every iteration MUST end in a grounded observation — an actual result with a status — and the next action is chosen from that observation, not from assumption. Treat snippets as leads; conclusions are earned by proof.

Transport: MCP or CLI

Use the Octocode MCP server tools when the host has them (oqlSearch / ghSearchCode / ghViewRepoStructure / ghGetFileContent / ghSearchRepos / npmSearch / ghHistoryResearch, plus local + LSP tools when present). Otherwise use the CLI (octocode <cmd>, or npx octocode if not installed). Same capabilities — pick by what the user has. Load references/tools.md when you need the exact MCP↔CLI mapping, status semantics, schema-first calling, or how to carry anchors across iterations.

The loop (all modes)

Frame — one line: goal + the single question this iteration closes + what observation would end the loop.
Act — issue ONE cheap call: the smallest query that could move the answer. Start broad/concise, then narrow.
Observe — read status first. empty = ran but matched nothing → check scope, spelling, branch, extraction mode, then broaden or switch path before concluding absence. error = correct the call (auth, validation, rate limit, scope) and retry. Results → capture exact anchors (path:line, match range, repo/PR/package id, branch).
Learn — update a short hypothesis map (likely answer, alternate, what would disconfirm each). Pick the next cheapest step that could confirm or kill a branch.
Repeat until a stop test passes.

Keep ≥2 plausible explanations alive while any is unsettled. Never let a single unverified snippet collapse the map.

Pick the mode

General research loop — when goal and path are clear on a single surface, read references/research-loop.md.
Local code checks & findings loop — when looping over workspace code where search / AST / LSP / tests are the ground-truth "compiler", read references/code-check-loop.md.
Full multi-source research loop — when the question spans local + GitHub + npm + history + web as chained sub-loops, read references/full-research-loop.md.
Loop mechanics, principles, stopping, best-of-K, budgets — read references/loop-protocol.md before running any mode.

Stop tests (don't over- or under-run)

Set multiple exits — don't trust one. Stop when ANY fires: the framed question is answered with grounded evidence and the alternate is killed; the cheapest next step can no longer change the conclusion; the iteration or token budget is hit; or no-progress is detected (the last N steps changed no state). Otherwise keep going — agents tend to stop early after one good hit. Before stopping, run one reflection pass: weakest claim, strongest counter-evidence, whether one more cheap call would flip it. If a loop stalls (repeats, same empty/error), change the surface or query shape rather than retrying verbatim — see references/loop-protocol.md.

Output contract

End with a compact result, not a transcript: Answer, Evidence (anchors like file:line/repo/package/commit), Loop trace (only decisive iterations), Verification (the deterministic check actually run, or say none), and Open gaps (what remains unproven). If the trace cannot fit comfortably, summarize the ledger and keep exact anchors.

Gates

Read the relevant mode reference before running that loop; read references/tools.md before the first raw-tool/schema call.
Verify before concluding: prove a finding with a deterministic check first (test, build, AST/structural match, LSP, exact read, history) — an LLM judge only for the unquantifiable, never your own say-so alone. Do not record a conclusion from a lead.
Keep the loop on a leash: gate expensive or irreversible actions (clone, test run, any write) on a surviving lead, and checkpoint with the human before the irreversible ones.
Surface a brief loop trace (iterations, key observations, final evidence) so the path is auditable.