Report (analyze now, resolve nothing)

/aid-report analyzes data/usage now and returns a curated, verified insight report. Like /aid-research it resolves nothing -- it presents the picture and you decide -- but its subject is data (a dataset, logs, telemetry, metrics, an A/B result) rather than an open question.

• Boundary: aid-report = a one-time analysis + insight. A durable, refreshable BI view is /aid-create-dashboard, not this. If the user wants the analysis to recur, that's a printed handoff to /aid-create-dashboard.
• Not a numbered pipeline phase; does not route to /aid-execute.

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

---

State: INTAKE

1. Require a subject. Empty argument -> ask one bootstrapping question ("What data should I analyze, and what question about it?") and wait.
2. Pick the path: Fast -- a clear data source + a clear analytical ask ("analyze the A/B results in results.csv", "error-rate breakdown from these logs") -> analyze now. Guided -- vague ("analyze our usage") -> scope which data, which metrics, what question first, then analyze.
3. Classify complexity (model + effort): simple (small dataset, one metric) -> aid-researcher at sonnet / medium; standard/complex (large data, A/B significance, deep telemetry) -> opus / high. Verifier tier >= 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, no prompt. Works exist -> ask new-vs-continuation; on continuation route to the chosen work's resume door and STOP (allocate nothing); on new work: 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), then allocate (pipeline.path: lite, initiator: aid-report, lifecycle: Running, active_skill: aid-report; phase not driven), same as the other collapse skills.

Advance: ANALYZE.

---

State: ANALYZE

Access the data read-only and dispatch aid-researcher (clean context, tiered) to analyze + consolidate:

• Data access: files / logs / exports -> read directly (never mutate the source). A live DB / analytics / telemetry service -> MCP-first connector (connectors/consumption-protocol.md): scan .aid/connectors/INDEX.md, request the connection from the host MCP; no catalogued connector -> ask the user for the export. Optional, never blocks.
• Two-tier grounding (enforced): the data + KB/source (what a metric means) are authoritative; external baselines/benchmarks are supplementary, cited URL + date. A data-vs-KB-assumption contradiction is surfaced with its reason, never resolved.
• It writes REPORT.md into the work folder (see Response shape).

Advance: VERIFY.

---

State: VERIFY

1. Mechanical grounding check (no dispatch): findings cite the data; external claims a URL+date; the Caveats and Conflicts sections exist.
2. Adversarial verification -- clean-context aid-reviewer checks REPORT.md: findings supported by the data; no metric or A/B conclusion stated without its caveat (sampling, significance, denominator, confounders); conflicts surfaced with reasons; conclusions not overstated into resolutions. Writes a review-quality ledger to .aid/.temp/review-pending/<work>-verify.md.
3. Grade: bash .aid/runtime/scripts/grade.sh --explain <ledger>. Not clean -> loop to ANALYZE. Circuit-breaker: 3 cycles -> IMPEDIMENT + lifecycle: Blocked.

Advance: PRESENT.

---

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

Set lifecycle: Paused-Awaiting-Input. Present REPORT.md clearly: findings (metrics/tables), conclusions (+/-), caveats & data-quality gaps (first-class), conflicts with reasons, and gaps. Assert no resolution.

Advance: HANDOFF (optional) then DONE.

---

State: HANDOFF (optional; printed suggestions only)

Printed suggestions the user may act on: make it recurring (/aid-create-dashboard), record a decision (/aid-document-decision), 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 lifecycle: Completed, updated now, append a ## Lifecycle History row. Keep the work folder (REPORT.md, the verify ledger) as the audit record.

---

Response shape

REPORT.md, sections in order:

1. Question / Scope -- the analytical ask, as scoped.
2. Data & method -- what data, its source, and how it was analyzed.
3. Findings -- the metrics / tables / EDA output.
4. Conclusions -- positive and negative, each tied to a finding.
5. Caveats & data-quality gaps -- sampling, confounders, significance, missing data; none only if genuinely none.
6. Conflicts & contradictions -- data<->KB especially, each with its reason + citations; none if none.
7. Sources -- data source(s) + KB/file:line (authoritative) and external baselines URL (accessed YYYY-MM-DD) (supplementary), separated.

---

Constraints

• Resolves nothing; presents findings/conclusions/caveats/conflicts/gaps.
• Read-only on the data source; never mutates it.
• Two-tier grounding, enforced; data<->KB conflicts surfaced with reasons.
• Caveats are mandatory -- a metric/A-B conclusion without its caveat fails VERIFY.
• Clean context; verification always a sub-agent (aid-reviewer).
• Boundary: durable/refreshable dashboards are /aid-create-dashboard, not this.
• Tracking: write STATE lifecycle at every transition.