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)

1. Frame — one line: goal + the single question this iteration closes + what observation would end the loop.
2. Act — issue ONE cheap call: the smallest query that could move the answer. Start broad/concise, then narrow.
3. 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).
4. 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.
5. Repeat until a stop test passes.

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