analysis-readout

Analysis Readout (Orchestrator)

Purpose

Coordinate a sequence of atomic skills for open-ended analytics requests. This skill does not perform analysis itself — it runs the right atomic skills in the right order and assembles their outputs into a single report.

When to use

• The user has a business question and a dataset but has not scoped the analysis type
• The ask is open-ended: "phân tích tình hình kinh doanh", "find what matters in this data", "tell me what's going on with X"
• The request likely requires more than one analytical lens before a recommendation is possible

When not to use

• The user explicitly names a specific analysis type (use that atomic skill directly)
• The question is already fully scoped and one atomic skill is the clear match
• The ask is a single standalone memo or report with known inputs (use stakeholder-memo directly)

Assumption policy

Proceed with stated assumptions. Do not stop to ask clarifying questions unless a required input (dataset, metric definition, timeframe) is genuinely missing and cannot be inferred. State assumptions explicitly at the top of the report instead.

Evidence constraint

Every conclusion produced by any skill in this pipeline must be grounded in specific data — a number, a rate, a segment, or a timeframe. Do not speculate or assert without an evidential basis. If data is insufficient to support a conclusion, state explicitly what is missing rather than filling the gap with unsupported inference. When evidence is weak, use hedged language ("consistent with," "suggests," "leading hypothesis") rather than asserting certainty.

Pipeline

The pipeline has four phases. The question assessment, steps 1–2, and the final step are fixed. The diagnostic phase (step 3) is dynamic.

pipeline:

  # Phase 0 — always run first, before any analysis
  question_assessment:
    - skill: clarify-question
      required: true
      note: "Assess the user's question before any analysis begins. Identify missing elements (metric, dimension, grain, timeframe, baseline, filter, decision context). If elements are missing and cannot be inferred, ask the minimum clarifying questions. If the user cannot answer, state working assumptions explicitly and proceed. Do not skip this step even for seemingly clear questions."

  # Phase 1 — always run, in order
  fixed_foundation:
    - skill: data-quality-check
      required: true
      note: "Run after question assessment. Flag issues but do not stop — proceed with clean subset and document exclusions."

    - skill: metric-definition
      required: false
      condition: "Any key metric, KPI, or column label in the dataset is ambiguous, unnamed, or could be measured in multiple valid ways (e.g. revenue = gross or net? activation = what event?). Run before EDA so interpretation is grounded in agreed definitions."
      note: "Produces a metric spec for each ambiguous KPI. Output feeds directly into EDA framing."

    - skill: exploratory-data-analysis
      required: true
      note: "Summarize shape, distributions, trends, and anomalies. This is the factual foundation."

  # Phase 2 — dynamic dispatch: select any skills whose condition is met based on EDA findings
  # Run all triggered skills; run multiple in parallel where findings are independent.
  # No skill is pre-selected — the EDA output determines what runs.
  diagnostic_phase:
    select: "all skills whose condition is met"
    available:
      - skill: root-cause-analysis
        condition: "A metric changed, declined, or spiked, OR a 'why' question is in scope."
      - skill: segmentation-analysis
        condition: "An audience, product, channel, or regional breakdown would change the recommendation."
      - skill: cohort-retention
        condition: "Retention, repeat purchase, or time-since-first-event patterns are relevant."
      - skill: funnel-analysis
        condition: "A conversion funnel or sequential drop-off is in scope."
      - skill: forecasting-readout
        condition: "A forward-looking projection or trend extrapolation is needed."
      - skill: experiment-readout
        condition: "An A/B test, holdout, or intervention is present in the data."
      - skill: causal-inference-check
        condition: "A causal claim is made or implied by the user or by EDA findings."
      - skill: hypothesis-tree
        condition: "The problem space is unclear after EDA and needs structured decomposition."
      - skill: dashboard-critique
        condition: "The input dataset is a dashboard export or reporting artifact, OR the analysis output is intended to populate or review an existing dashboard."

  # Phase 2.5 — run after diagnostics, before synthesis
  # Triggered when analysis reveals gaps the current data cannot close.
  gap_resolution:
    - skill: data-request-spec
      required: false
      condition: "EDA or any diagnostic skill identifies a specific data gap — missing fields, unmeasured events, unavailable history — that would materially change a finding or leave a key recommendation unsupported."
      note: "Produces a precise request spec for data/engineering teams. Attach to the memo as an appendix so stakeholders see what is needed to close open questions."

  # Phase 3 — always the final step
  synthesis:
    - skill: stakeholder-memo
      required: true
      note: "Synthesizes all prior outputs into a decision-ready memo. Always the last step."

assumption_policy: "state working assumptions explicitly after clarify-question; do not stop mid-pipeline to re-clarify"
output_artifact: "report-{date}.md"