Terminal
Terminal/Skill
Guides an analyst through a data investigation, from a one-sentence answer to a reproducible memo, testing competing hypotheses along the way.
By Kilo Code
Works with
npx skills add kilo-org/skills --skill data-investigationUse this skill to produce investigations that are fast, correct, reproducible, and communicate a clear conclusion rather than a pile of charts.
Every investigation should be answerable in one sentence before the first SQL query is written.
Before writing any SQL, write the sentence the conclusion is expected to be.
Example: The cohort size gap is a definition problem rather than a product behavior problem.
If the sentence cannot be written, the question is not yet understood.
| Type | Trigger | Approach |
|---|---|---|
| Gap analysis | Why do A and B not match? | Establish the gap, localize it, explain it |
| Root cause | Why did this metric change? | Confirm real, isolate segment, align timing, validate mechanism |
| Hypothesis test | Is X causing Y? | Define what must be true, test sub-claims, confirm or reject |
| Feasibility check | Is this number trustworthy? | Check grain, joins, nulls, definition overlap |
Never investigate with a single hypothesis. That creates confirmation bias.
Order hypotheses by plausibility and note which one is currently expected to be correct and why.
Step 1 always confirms the anomaly is real and measures its magnitude. Do not jump to cause until the effect is confirmed.
select
<time_bucket>,
<source_a_count> as metric_a,
<source_b_count> as metric_b,
<source_a_count> - <source_b_count> as gap,
round(100.0 * (<source_a_count> - <source_b_count>) / nullif(<source_a_count>, 0), 1) as pct_gap
from ...
order by 1
After confirming the gap, break it down along one dimension per step:
Once the anomaly start date is known, check:
A credible root cause must explain why the metric changed when it did.
After identifying a candidate cause, confirm it mechanically:
Do not stop at correlation.
For every candidate explanation, produce a number.
Examples:
H1 accounts for 1,240 usersH2 accounts for 1,050 usersIf a hypothesis cannot be quantified, it is not yet validated.
Investigation SQL should be reproducible. Favor fixed bounds over rolling windows unless the analysis is intentionally operational and evergreen.
-- Prefer fixed investigation scope
where created_at >= '2026-02-16'
and created_at < '2026-04-04'
-- grain: one row per user
with users as (
...
)
Bad:
select count(*) from ...
Better:
select
count(*) as users_in_scope,
count(distinct org_id) as orgs_in_scope
from ...
Diagnostic SQL exists to answer one question. Do not build giant reusable queries too early.
The first sentence of the written output should state the conclusion.
Bad:
I looked at several possible explanations for the discrepancy.
Good:
The discrepancy is caused by internal users being excluded from the dashboard query but included in the warehouse baseline.
Use a structure like:
Every investigation should state the biggest assumption that could change the answer.
Example:
This conclusion assumes backend event timestamps are complete for the affected week; if ingestion was delayed, the gap may be overstated.
Every completed investigation should leave behind:
answering-natural-language-questions-with-dbt when the goal is answering a business question rather than debugging why analysis or metrics disagree.