borda/ai-rig/research

Before asking, read User Questions. Waits, plan updates, and test runs follow Agent Waits, Plan Updates, and Sandboxed Test Runs.

Research

Task-size routing follows Proportional Execution; this skill's specialized lifecycle and acceptance checks remain authoritative.

Source-backed research for documentation, API migration, paper, or state-of-the-art questions.

Input Schema

{
  "question": "required research question",
  "mode": "docs|sota|paper|methodology|code-fidelity",
  "constraints": [
    "optional codebase, compute, version, or implementation constraints"
  ],
  "done_when": "recommendations are source-backed with caveats and confidence"
}

Workflow

01: Create run directory

Run create_run.py --skill research per ../../shared/helper-cli-contract.md.

02: Define research question, mode, and constraints

Modes:

• docs: current API/docs/migration answer.
• sota: method comparison and implementation recommendation.
• paper: single-paper analysis.
• methodology: experiment design, metric, guard, and ablation review.
• code-fidelity: compare paper/spec claims against implementation.

03: Gather sources

Write <run-directory>/sources.md:

| Source | Type | Date/version | Why reliable | Used for |
| --- | --- | --- | --- | --- |

Source rules:

• Prefer primary docs, papers, specs, release notes, code.
• Use current live sources for volatile docs, dependencies, APIs.
• Mark stale/unavailable source explicitly.
• Never cite secondary summaries for high-impact claims unless independently corroborated.

For sota, paper, methodology, or code-fidelity, read and apply ../../shared/specialist-orchestration.md only when independent expertise improves correctness; otherwise never load it. Write <run-directory>/specialist-research-plan.md with context packs for the axes below; planning only here, dispatch is the end of step 04 once the codebase context exists:

• web-explorer: current docs, release notes, API and dependency changes.
• scientist: formulas, methodology, metrics, ablations, benchmark claims.
• solution-architect: only when user expressly requests that advisory pass or selects the role for implementation fit, API boundaries, or migration shape; it returns a bounded read-only design artifact to the parent/session for next action and acceptance.
• squeezer: performance or resource claims.
• data-steward: datasets, splits, leakage, reproducibility.
• challenger: unsupported recommendation or overconfident source synthesis.

Never send full papers, repositories, or all search results to every specialist. Give each only source excerpts, code files, questions needed for its axis.

04: Map to codebase context when implementation is relevant

Inspect PLUGIN_ROOT/bin/python PLUGIN_ROOT/shared/collect_diff.py --help; collect working-tree scope into <run-directory>/baseline. Run topic scan separately; record unavailable paths/collection failures as evidence gaps.

Structural context (optional): for sota/code-fidelity questions naming Python module/symbol, also probe codemap-py once: PLUGIN_ROOT/bin/python PLUGIN_ROOT/shared/codemap_adapter.py context --category analysis [--target <qname>] --out <run-directory>/codemap-context.json. Per ../../shared/codemap-contract.md, absence/incompatibility is non-fatal — continue with codebase mapping above. Persist result once here; any specialist context pack planned in step 03 includes <run-directory>/codemap-context.json, with added queries only under the contract's bounded Specialist follow-up queries rule.

When step 03 planned specialists, dispatch that single approved wave now, before step 05, and join all handoffs before writing research.md.

05: Produce <run-directory>/research.md with:

• Question
• Constraints
• Source Table
• Findings
• Comparison for SOTA/method choices
• Implementation Fit
• Risks And Unknowns
• Recommendation
• Next Checks

06: For paper/code-fidelity mode, include dimensions:

• F: formula/math match
• H: hyperparameter parity
• E: evaluation protocol
• N: notation and naming consistency
• C: citation/derivation chain

07: Run review gate

Run git diff --check -- <run-owned paths> as argv command, limited to files this run edited or generated for executable validation, so unrelated caller edits never decide the result; with no such paths record that absence instead. Write its combined output to <run-directory>/review.txt and retain its exit status as review evidence; never erase nonzero result.

08: Run shared gates and write the validated result artifact

Follow ../../shared/helper-cli-contract.md and authoritative help. For research-only work, mark lint, format, types, tests inapplicable with concrete reasons; review requires non-empty research.md, sources.md, clean diff check. Write RESEARCH_METADATA, validate as research, promote only validated candidate.

Replace explicit skip with relevant command when research includes executable validation.

Fail-Fast Rules

1. Missing question => fail.
2. No primary sources for high-impact/current claims => fail.
3. Recommendation not tied to constraints => fail.
4. Paper/code-fidelity claim without code or source reference => fail.
5. Result artifact missing => fail.

Quality Gates

Required:

• review: source table, caveats, git diff --check on run-owned paths.

Conditional:

• tests: when research includes executable validation or code-fidelity probe.

Calibration Hooks

On source-protocol/recommendation-policy change, update calibration:

• behavioral cases: stale docs, unsupported SOTA claim, paper-code mismatch
• benchmark patterns: research

Output Contract

Before writing result candidate, follow ../../shared/final-handoff-contract.md: render and bind final-handoff.json, final.md, and final-handoff.validation.json; after both validators and promotion pass, emit final.md verbatim.

Use ../../shared/quality-gates.md.

Final chat

Final chat follows shared frame with Next steps. Outcome: recommendation/support level. Results: exactly Recommendation | Evidence | Decision | Caveat / next check, one row/recommendation. Include source freshness and each gap/caveat's next check.

Minimum artifact payload template: result-template.json.