Autoresearch Improvement Loop

Autoresearch Workflow

Use when the user asks for autoresearch, or gives a bounded research goal whose deliverable is a defensible verdict rather than code ("find out", "investigate", "benchmark and draw a conclusion").

Usage

/skill:autoresearch "<research goal>"
/skill:autoresearch --spec .gjc/_session-{sessionid}/specs/deep-interview-<slug>.md

Invoke this workflow as /skill:autoresearch; the durable state behind it is driven by the gjc autoresearch runtime command.

Purpose

autoresearch runs one goal-directed research mission: it interleaves web research with data/environment experimentation and ends on a single structured, best-effort verdict. The verdict receipt carries a structured status, evidence[], caveats[], and the evaluator identity that issued it. The mission is research, NOT implementation: its durable outputs are findings, evidence, run records, and a verdict — never product code.

All mission state persists per session under .gjc/_session-{sessionid}/autoresearch/ and survives across gjc autoresearch invocations. The global ~/.gjc/autoresearch store is never written.

Always-used command examples

Use these exact gjc autoresearch commands before spending tool calls rediscovering syntax:

gjc autoresearch --spec <deep-interview-spec-path>
gjc autoresearch "<goal>"
gjc autoresearch
gjc autoresearch read --json
gjc autoresearch clear

• intake --spec <path> (or the bare --spec flag) — spec intake from a persisted deep-interview spec; asks zero questions.
• "<goal>" or bare invocation — cold intake; goal, constraints, and deliverables must be clarified before research begins.
• read --json — current mission artifact plus the append-only ledger snapshot.
• clear — retire the mission artifact and its working set, recording mission_cleared in the ledger. This never touches the session python REPL kernel; reset that with the python tool's own clear action.

Use when

Use when the user wants a bounded research mission whose output is a defensible verdict: a question that needs evidence from the web, local data, or both before any conclusion is drawn ("does X hold for this dataset?", "which approach benchmarks best?", "what changed between these two releases?"); an explicit request to run autoresearch; or a goal whose acceptance is a structured verdict with evidence and caveats.

Do not use when

• Ordinary pre-planning lookup that will be followed by a planning pass — route that through ralplan/deep-interview instead of opening a research mission.
• Implementing anything — autoresearch produces findings and a verdict, never code. Downstream implementation goes through the normal approval-gated path.
• A quick single answer that one read/search resolves directly.

Two intakes

Both intakes write the same mission artifact (objective, mode, deliverables, constraints, slug).

Spec intake

gjc autoresearch intake --spec <path> (or the bare --spec flag) reads a persisted deep-interview spec and starts the mission with zero clarification questions. The spec MUST declare its mission mode explicitly (a line like autoresearch-mode: web); a missing or invalid declaration is a hard fail. The consumed spec path and handoff time are recorded on the mission artifact.

Cold intake

gjc autoresearch "<goal>" (or a bare gjc autoresearch) signals cold intake. Clarify the goal, constraints, and deliverables BEFORE any research tool fires — no web search, no python kernel, no harness build — then write the mission with an explicit mode.

Mode

Every mission carries an explicit mode: web, mixed, or data. The mode is stated at intake and persisted in the mission artifact. It is NEVER inferred from the presence of a data file: a data file in the workspace without an explicit mode is a rejection, not a default. Data-context loading is gated to data/mixed mode only; web mode never attaches data context.

Goal mode (nudge until verdict)

Autoresearch asks the agent to drive its mission through GJC goal mode: an inline goal keeps the autonomous continuation loop nudging the agent through intake → research → verdict until the mission's structured verdict receipt exists. This is a cooperative, instruction-only integration, not an autoresearch runtime enforcement boundary: the agent calls the unified goal tool itself; gjc autoresearch commands and hooks never mutate goal state; and no autoresearch-specific nudge budget or ask blocking applies. Generic goal-runtime guards, abort behavior, and handoff behavior still apply and can leave a mission or goal open; the agent must surface or retry those failures rather than treating them as completed lifecycle steps.

Lifecycle:

• Create — right after the mission artifact is written (both spec and cold intake), call goal({"op":"get"}); create only when it returns no goal or a terminal complete/dropped goal. Use goal({"op":"create","objective":"Drive the autoresearch mission '<mission objective>' to a persisted structured verdict receipt"}). No goal exists during intake questioning, so ask-driven cold-intake clarification is unaffected.
• Collision rule — an active or paused goal is a collision, not an invitation to call create: never replace, resume, complete, or drop a different goal. If the existing goal has this mission's exact objective, continue its lifecycle; otherwise run the mission without goal mode and leave the other goal untouched. This matters because the goal runtime rejects create over any nonterminal goal, including a paused one.
• Resume rule — when re-entering a mission (gjc autoresearch read --json), inspect both the latest persisted verdict and goal({"op":"get"}). With no verdict or an explicit status.disposition: "inconclusive", create a goal only when no goal or a terminal goal exists; resume a matching paused goal with goal({"op":"resume"}), continue a matching active goal, and honor any different active/paused goal as a collision. With status.disposition: "conclusive", never create or resume a new goal: complete the matching nonterminal goal if one exists, otherwise retry only the pending mission clear. A missing or different disposition is treated as open rather than auto-cleared.
• Complete — after a structured verdict receipt is persisted under .gjc/_session-{sessionid}/autoresearch/, call goal({"op":"complete"}) exactly once for the matching nonterminal mission goal. Any verdict completes the goal-tracking pass, including best-effort and inconclusive verdicts; an inconclusive mission stays open for follow-up, but its current goal pass is complete. Verdict writes themselves are append-only and not idempotent: after an uncertain verdict command, read the latest ledger/receipt before retrying and do not issue a duplicate verdict merely because the first response was lost. If goal completion or the following clear fails, retain the durable state and retry on re-entry rather than issuing a second completion or dropping a completed goal.
• Auto-clear — only status.disposition: "conclusive" is terminal for mission cleanup; best-effort evidence and confidence do not by themselves determine terminality. Immediately after completing the matching goal, run gjc autoresearch clear so no stale conclusive mission artifact lingers. This automatic clear follows a completed goal and never calls goal({"op":"drop"}); if the clear fails, retry it on re-entry without creating a new goal. Inconclusive, missing, or other dispositions skip the clear — the mission stays open for follow-up under the existing non-terminal contract.
• Drop — call goal({"op":"drop"}) only for this mission's matching nonterminal goal, whether active or paused: on a manual gjc autoresearch clear (pre-verdict or open-inconclusive mission), on handoff to /skill:ralplan, /skill:deep-interview, or /skill:ultragoal, and on user cancel. Never drop a different goal. The post-verdict auto-clear is exempt — its goal is already complete, and a completed goal is never dropped.

The runtime does not make these transitions transactional: gjc autoresearch clear and canonical skill handoff do not drop an inline goal for the agent, user cancellation can preserve an active goal, and the generic runtime does not itself prevent a caller from dropping a completed goal. Before a manual clear or handoff, drop the matching goal explicitly when the turn still permits tool calls; after cancellation or a failed handoff, re-enter, inspect goal({"op":"get"}), and clean up only a matching nonterminal goal. An unrelated or unreadable Ultragoal state can also reject generic goal operations; do not bypass that guard or clear mission state early.

Goal mode never authorizes implementation: the mission remains research-only (findings, evidence, run records, verdict), and the nudge loop must never be used to start product-code changes.