Research (investigate now, resolve nothing)

/aid-research investigates an open question now and returns a curated, verified answer -- the complete picture, presented clearly. It is aid-ask's bigger sibling: where aid-ask retrieves an answer that already exists in the project's context (one read-only pass, no work folder), research builds a new judgment for a question the available context can't already answer -- with option evaluation, external context, an optional authorized spike, verification, and a human-facing presentation.

Resolves nothing. No "I recommend X." It lays out conclusions (+/-), conflicts, and gaps; the user decides.
Not a numbered pipeline phase; it does not route to /aid-execute.

State machine: INTAKE -> INVESTIGATE (-> PROPOSE-SPIKE?) -> VERIFY (loop) -> PRESENT [human resolves] -> HANDOFF? -> DONE. Print the [State: NAME] -- {purpose} entry line on each state.

State: INTAKE

Require a question. If the argument is empty, ask one bootstrapping question ("What do you want investigated?") and wait.
Pick the path (question scope):
- Fast path -- a concrete, well-scoped question with clear evaluation criteria ("Is lib X compatible with our Node 24 build?", "Postgres vs SQLite for use-case Y against criteria A/B/C") -> investigate immediately.
- Guided path -- vague / broad / underspecified ("research our DB options") -> ask 2-3 scoping questions first (narrow it), then investigate.
Classify complexity (sets model + effort): simple (bounded question, a few docs, <=1 web source) -> aid-researcher at sonnet / medium; standard/complex (broad options analysis, deep traversal, many web sources, a spike) -> opus / high. Verifier tier is always >= producer tier.
Consult the Work Initiation Gate, then allocate the work folder + STATE. First run the gate (.aid/runtime/templates/work-initiation-gate.md): bash .aid/runtime/scripts/works/enumerate-works.sh (main tree + every git worktree). Empty -> allocate below, no prompt. Works exist -> ask new-vs-continuation with the enumerated list; on continuation route to the chosen work's resume door and STOP (allocate nothing); on new work: resolve <work-id> as work-{NNN+1}, where NNN is the maximum work-NNN numeric prefix across every record the enumeration above already returned (cross-worktree by construction -- never a local .aid/works/ glob; gate § 3a step 1); create and enter the worktree per the gate's § 3a step 2 (worktree-lifecycle.sh create <work-id> <name>, STOP on a non-zero exit or empty path, else enter the resolved path); only then allocate: .aid/works/<work-id>-<slug>/ under .aid/works/; slug from the question. Copy .aid/runtime/templates/work-state-template.yml to .aid/works/work-NNN-<slug>/STATE.yml; write opening frontmatter (pipeline.path: lite, initiator: aid-research, lifecycle: Running, active_skill: aid-research, started/updated). Do NOT drive the 7-phase phase scalar. Associate a git worktree only if a spike is later authorized (INVESTIGATE).

Advance: INVESTIGATE.

State: INVESTIGATE

Dispatch aid-researcher (clean context, model+effort from INTAKE Step 3) to gather and curate the evidence:

Two-tier grounding (enforced): read the KB (.aid/knowledge/) + the project source as the authoritative base; enrich with external/web sources as needed, cited with URL + access date. Every project claim cites a KB doc or file:line; every external claim cites a URL+date.
It writes a structured RESEARCH.md into the work folder (see Response shape).

Spike escalation (conditional, human-authorized). Default is analytical-with- handoff -- no code is written. If the researcher determines a gap genuinely cannot be closed on paper, it returns a spike proposal instead of a final answer, and the skill enters PROPOSE-SPIKE: present what it would build, where (isolated in the work folder / opt-in worktree, never touching production), and what it would learn, then STOP for the user's decision. On authorization -> re-dispatch aid-researcher to write the throwaway spike (isolated), fold the finding into RESEARCH.md, continue. On decline -> proceed analytically and state the resulting limit in the Gaps section.

Advance: VERIFY.

State: VERIFY (who reviews the researcher)

Mechanical grounding check (no dispatch): every project claim carries a KB/source cite; every external claim a URL+date; the Conflicts and Gaps sections exist (empty-but-present is allowed; silently-omitted is not).
Adversarial verification -- dispatch a clean-context aid-reviewer to check RESEARCH.md: claims grounded and correctly attributed; conclusions evidence-backed and not overstated into resolutions; every KB<->web conflict surfaced with its reason; no material angle of the question left silently unaddressed. It writes a review-quality 7-column ledger (reviewer-ledger-schema.md) to .aid/.temp/review-pending/<work>-verify.md.
Grade the response: bash .aid/runtime/scripts/grade.sh --explain <ledger>. Not clean -> loop back to INVESTIGATE for the researcher to revise. Circuit-breaker: 3 cycles -> write .aid/works/{work}/IMPEDIMENT-research.md, set STATE lifecycle: Blocked, surface it.

(Single grade -- the response is the deliverable; there is no separate target artifact.)

Advance: PRESENT.

State: PRESENT (always a hard stop -- the user resolves)

Set STATE lifecycle: Paused-Awaiting-Input. Present RESEARCH.md clearly and simply: the in-depth answer, conclusions (positive and negative), conflicts/contradictions with their reasons, and gaps. Assert no resolution -- the user decides. Negatives and gaps are first-class, never buried under positives.

Advance: HANDOFF (optional) then DONE.

State: HANDOFF (optional; printed suggestions only)

Offer the natural next steps as printed suggestions, each requiring the user to act: record an ADR (/aid-document-decision -> once landed, /aid-create-document), update the KB (/aid-update-kb), act on a conclusion (/aid-create* / /aid-update*), or comment on a source ticket (/aid-update-ticket comment [<connector>:]<ticket-id> <text>). Never auto-invoked; never a resolution.

Advance: DONE.

State: DONE

Set STATE lifecycle: Completed, updated now, append a ## Lifecycle History row. Keep the work folder (RESEARCH.md, any spike scratch, the verify ledger) as the audit record.

Response shape

RESEARCH.md (the "clear + simple" deliverable), sections in order:

Question -- the query, as scoped/investigated.
Answer -- the in-depth, curated response.
Conclusions -- positive and negative, each evidence-backed and cited.
Conflicts & contradictions -- especially KB<->web, each with its reason and both citations; none if there were none.
Gaps -- what could not be answered / stays uncertain (incl. any limit from a declined spike); none if none.
Sources -- KB docs + file:line (authoritative) and external URL (accessed YYYY-MM-DD) (supplementary), clearly separated.

Constraints

Resolves nothing -- curated information + conclusions/conflicts/gaps; never a directive.
Two-tier grounding, enforced (VERIFY step 1 + the researcher brief): KB+source authoritative, web supplementary + cited; KB<->web contradictions surfaced with reasons, never silently resolved.
Clean context -- INVESTIGATE and VERIFY never share context.
Verification is always a sub-agent dispatch (aid-reviewer), never inline.
Human final say before any commit -- a spike (code), a KB update, a decision doc, or a ticket comment happens only on explicit authorization; presenting the answer is not a commit.
Tracking: write STATE lifecycle at every transition.

aid-research

SKILL.md.claude/skills/aid-research/SKILL.md