aid-research

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

1. Require a question. If the argument is empty, ask one bootstrapping question ("What do you want investigated?") and wait.
2. 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.
3. 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.
4. 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).