skilldrop-cli 0.16.3__py3-none-any.whl

skilldrop_cli/data/packs/research/skills/hypothesis-comparison/evals/eval_queries.json

@@ -0,0 +1,34 @@
+[
+  {
+    "query": "Our signup rate fell 25% last week and we have four theories. Which one does the evidence actually support?",
+    "should_trigger": true
+  },
+  {
+    "query": "Run an analysis of competing hypotheses on why our API latency doubled after the migration",
+    "should_trigger": true
+  },
+  {
+    "query": "Build a consistency matrix for these rival explanations of the churn spike and tell me which one survives",
+    "should_trigger": true
+  },
+  {
+    "query": "The team keeps arguing about what caused the drop in NPS. Help me weigh the competing explanations against the evidence.",
+    "should_trigger": true
+  },
+  {
+    "query": "Compare Snowflake, BigQuery and Databricks for our analytics platform and recommend one",
+    "should_trigger": false
+  },
+  {
+    "query": "Do a SWOT on entering the Canadian market",
+    "should_trigger": false
+  },
+  {
+    "query": "Summarise these five papers on remote work and productivity, with citations",
+    "should_trigger": false
+  },
+  {
+    "query": "Critique this root-cause write-up before I send it to the VP",
+    "should_trigger": false
+  }
+]

skilldrop_cli/data/packs/research/skills/hypothesis-comparison/evals/evals.json

@@ -0,0 +1,19 @@
+{
+  "skill_name": "hypothesis-comparison",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Acme's monthly churn on the Starter plan went from 2.1% in July to 3.4% in August. Theories: the price rise from $19 to $24 on 1 Aug, a new competitor (Northwind Lite) launching in late July, or the onboarding email sequence that broke on 20 Jul. Evidence: churn rose on monthly and annual-renewal customers alike; cancellation survey 'too expensive' share went from 30% to 32%; customers who signed up after 20 Jul churn at 5.8%, older cohorts at 2.4%; win-back calls mention Northwind Lite twice out of 40. Which explanation fits best and what should we check next?",
+      "assertions": [
+        "Lists at least four rival hypotheses, including a measurement or definition hypothesis the user did not raise",
+        "Builds a matrix rating every evidence item against every hypothesis as consistent, inconsistent or neutral (or CC/II/NA)",
+        "Ranks hypotheses by how much evidence contradicts them, not by how much supports them, and shows the scores or arithmetic",
+        "Names the non-diagnostic evidence (rated the same for every hypothesis) and does not use it as support",
+        "Names the linchpin evidence whose removal would change the leader, or states that none exists",
+        "Gives the conclusion a confidence word with a reason",
+        "Names one next observation that the top two hypotheses predict differently, with the result each predicts",
+        "Does not invent evidence, numbers or sources that are not in the prompt; anything inferred is tagged [assumption]"
+      ]
+    }
+  ]
+}

skilldrop_cli/data/packs/research/skills/hypothesis-comparison/examples/conversion-drop.md

@@ -0,0 +1,132 @@
+# Worked example — why did Northwind's mobile checkout conversion drop?
+
+## Input given to the skill
+
+> Our checkout conversion dropped about 18% starting Tuesday 8 Sep and everyone has a theory.
+> Engineering says it's seasonal, marketing thinks Contoso's 20%-off promo (launched 1 Sep) is
+> pulling people away, and I suspect the checkout release we shipped Monday 7 Sep at 22:00.
+> What we know:
+> - last September we never saw a dip bigger than 3%
+> - sessions and add-to-cart are flat week on week
+> - it's only mobile Safari; desktop and Android look normal
+> - the payment provider's dashboard shows settled orders down 17% for the same days
+> - support tickets about "card declined" or "button not working" doubled since the 8th
+> - the tag manager container was also republished on the 7th
+> - our synthetic checkout test on iOS Safari has passed on every run since the release
+>
+> Which explanation actually fits?
+
+---
+
+## Output
+
+# Competing hypotheses: Northwind mobile checkout conversion drop
+
+_Prepared 2026-09-15 · Evidence as of 14 Sep · Method: analysis of competing hypotheses_
+
+## Observation
+
+Checkout conversion fell about 18% from Tue 8 Sep, on mobile Safari only.
+
+## Assumptions to confirm first
+
+- [assumption] "Conversion" means orders ÷ sessions in the web analytics tool, the same
+  definition used last September.
+- [assumption] The payment dashboard counts orders by settlement date, so its 17% fall covers
+  the same days as the conversion drop.
+- [assumption] The Safari-only split comes from the order records, not only from the analytics
+  tag. If it comes from the tag, E4 says nothing about H4.
+
+## Hypotheses
+
+| Id | Hypothesis | Could be true alongside |
+|---|---|---|
+| H1 | The 7 Sep checkout release broke payment for some iOS Safari users | H3 |
+| H2 | It's a normal seasonal dip | H3 |
+| H3 | Contoso's promotion is taking buyers who would have checked out with us | H1, H2 |
+| H4 | Nothing changed for customers; the 7 Sep tag manager change broke conversion tracking | none |
+
+H4 is the measurement hypothesis. Nobody had raised it, but the tag manager change on the
+same day makes it a real rival.
+
+## Evidence and matrix
+
+Rated row by row. Weights: E4 is 2 because a pattern this specific (one browser on one
+platform) is hard to produce by chance; E6 is 0.5 because a promotion's existence says little
+about who it affects.
+
+| Id | Evidence | Weight | H1 | H2 | H3 | H4 | Diagnostic? |
+|---|---|---|---|---|---|---|---|
+| E1 | Fall starts Tue 8 Sep; release went out Mon 7 Sep 22:00 | 1 | C | N | N | C | no |
+| E2 | Last September never dipped more than 3% | 1 | N | II | N | N | yes |
+| E3 | Sessions and add-to-cart flat week on week | 1 | C | I | I | C | yes |
+| E4 | Drop on mobile Safari only | 2 | C | I | I | N | yes |
+| E5 | Payment provider: settled orders down 17% | 1 | C | C | C | II | yes |
+| E6 | Contoso promo launched 1 Sep | 0.5 | N | N | C | N | no |
+| E7 | "Card declined" / "button not working" tickets doubled | 1 | C | N | I | I | yes |
+| E8 | Tag manager container republished 7 Sep | 1 | N | N | N | C | no |
+| E9 | Synthetic iOS Safari checkout test passes every run | 1 | I | N | N | N | yes |
+
+## Ranking
+
+Script output (`python3 scripts/ach_matrix.py conversion-drop.csv`), ranking section:
+
+```
+| Rank | Hypothesis | Inconsistency score | I | II | C or CC |
+|---|---|---|---|---|---|
+| 1 | H1 checkout release | 1 | 1 | 0 | 5 |
+| 2 | H4 tracking change | 3 | 1 | 1 | 3 |
+| 3 | H3 competitor promo | 4 | 3 | 0 | 2 |
+| 4 | H2 seasonal dip | 5 | 2 | 1 | 1 |
+
+**Least contradicted:** H1 checkout release (score 1), 2 ahead of H4 tracking change.
+```
+
+## What the ranking rests on
+
+- **Diagnostic evidence:** E4 (Safari only) and E3 (flat traffic) count against the seasonal
+  and promotion hypotheses, because both would hit every device and cut sessions. E2 rules out
+  "seasonal" almost alone. E5 (real orders down) is the one row against the tracking hypothesis.
+- **Non-diagnostic, set aside:** E1, E6 and E8. The timing (E1) is the reason the release
+  feels guilty, but it fits the tracking change just as well. The script flags all three:
+
+  ```
+  **Non-diagnostic:** E1, E6, E8. These count the same against every hypothesis, so they cannot help you choose. Keep them for completeness; don't cite them as support.
+  ```
+
+- **Linchpin:** E5. The script's sensitivity check:
+
+  ```
+  - **E5** (Payment-provider dashboard shows settled orders down 17% for the same days): without it, first place is H1 checkout release and H4 tracking change (tie)
+  ```
+
+  Everything that separates "customers are failing to pay" from "we stopped counting
+  properly" rests on the payment dashboard. Confirm it matches the order database for
+  7–14 Sep before acting on this ranking.
+
+## Conclusion
+
+**H1, the checkout release,** is the least contradicted explanation. Confidence:
+**moderate**, because the lead over H4 rests on one row (E5) that hasn't been cross-checked,
+and E9 counts against H1.
+
+H2 and H3 can be dropped as main causes: each conflicts with the Safari-only pattern and the
+flat traffic. H3 can still be acting in the background at a small scale.
+
+What would rule out each survivor:
+
+- **H1:** iOS Safari payment errors flat across the release, in the payment SDK logs.
+- **H4:** the order database agreeing with the payment dashboard that real orders fell 17%.
+
+E9 is worth a look on its own: the synthetic test may not cover the path real users take
+(saved cards, Apple Pay), which would make it a weaker row than its weight of 1 suggests.
+
+## Next observation
+
+| Check | H1 predicts | H4 predicts | Who | How long |
+|---|---|---|---|---|
+| iOS Safari payment SDK errors, 6–10 Sep, by hour | A step up after 22:00 on 7 Sep | No change | Payments engineering | Under an hour |
+| Order database count vs payment dashboard, 7–14 Sep | Both down about 17% | Database flat, which means the payment dashboard is wrong too | Data team | Half a day |
+
+Run the first check today. If it shows the step, roll back or hotfix the release and watch
+iOS Safari conversion for 48 hours.

skilldrop_cli/data/packs/research/skills/hypothesis-comparison/manifest.json

@@ -0,0 +1,43 @@
+{
+  "name": "hypothesis-comparison",
+  "version": "0.1.0",
+  "description": "Compare rival explanations for an observation with analysis of competing hypotheses (ACH) — list the hypotheses and the evidence, build a consistency matrix (consistent / inconsistent / neutral), rank hypotheses by how little evidence contradicts them rather than how much supports them, name the diagnostic evidence and the linchpins, and say which next observation would tell the leaders apart. Use when the user asks \"why did X happen\", \"which explanation fits the evidence\", \"what's really causing this\", wants to stop arguing over a favourite theory, or says \"compare these hypotheses\", \"competing explanations\", \"ACH\".",
+  "entrypoint": "SKILL.md",
+  "deps": {
+    "npm": [],
+    "pip": []
+  },
+  "env": {
+    "required": [],
+    "optional": []
+  },
+  "related": [
+    "doc-critique",
+    "postmortem-generator",
+    "research-plan",
+    "source-synthesis",
+    "strategy-analysis",
+    "tech-comparison-matrix"
+  ],
+  "handoff": [
+    {
+      "to": "research-plan",
+      "when": "the matrix has too little diagnostic evidence to separate the leading hypotheses",
+      "purpose": "Plan how to collect the observation that discriminates between them.",
+      "fallback": "If research-plan is absent, write the next observation as a test inline: what to check, what each hypothesis predicts, who gets it and how long it takes."
+    }
+  ],
+  "tags": [
+    "research",
+    "hypotheses",
+    "ach",
+    "root-cause",
+    "analysis",
+    "evidence"
+  ],
+  "permissions": {"network": [], "commands": [], "files": "named-paths"},
+  "model": {
+    "tier": "heavy",
+    "rationale": "Judgment-heavy: generating real rivals, rating every evidence-hypothesis cell honestly and resisting the favourite theory is where a fast pass fails; the script only does the arithmetic."
+  }
+}

skilldrop_cli/data/packs/research/skills/hypothesis-comparison/reference.md

@@ -0,0 +1,107 @@
+# hypothesis-comparison — reference
+
+## Where the method comes from
+
+Analysis of competing hypotheses (ACH) was set out by Richards J. Heuer Jr. in *Psychology of
+Intelligence Analysis* (CIA Center for the Study of Intelligence, 1999), chapter 8. The core
+idea: people tend to pick the most likely explanation and look for evidence that supports it.
+ACH reverses that. You set every hypothesis against every piece of evidence and look for the
+hypothesis with the least evidence **against** it, because a single solid inconsistency can
+rule a hypothesis out, while any amount of consistent evidence can't prove one.
+
+Heuer's steps, in short:
+
+1. Identify the possible hypotheses, ideally with a group so you get real rivals.
+2. List the significant evidence and arguments, including assumptions and the *absence* of
+   evidence you'd expect.
+3. Build a matrix with hypotheses across the top and evidence down the side. Judge each item's
+   consistency with each hypothesis, and how diagnostic it is.
+4. Refine the matrix: reword or merge hypotheses, and set aside evidence that isn't
+   diagnostic.
+5. Draw tentative conclusions by trying to disprove hypotheses, not prove them.
+6. Check how sensitive the conclusion is to a few critical items of evidence. What if they
+   were wrong, misread, or planted?
+7. Report the conclusion, with the relative likelihood of every hypothesis, not just the winner.
+8. Name milestones: future observations that would show events are taking a different course.
+
+This skill follows those steps. Two parts are this skill's own conventions, not Heuer's: the
+0.5–2 weight scale, and the scoring rule in the script (`I` = 1 × weight, `II` = 2 × weight).
+
+## Rating a cell
+
+Ask: **"If this hypothesis were true, how likely is it that we'd see this?"** Don't ask
+whether the evidence "supports" the hypothesis.
+
+| Rating | Use when | Example (H: "the checkout release broke payment on iOS Safari") |
+|---|---|---|
+| `CC` | The hypothesis predicts this specifically; other causes rarely produce it | Payment SDK errors on iOS Safari start at the release minute |
+| `C` | You would expect to see this if the hypothesis were true | More "button not working" tickets after the release |
+| `N` | The hypothesis says nothing either way | A competitor ran a promotion |
+| `NA` | The evidence doesn't apply to this hypothesis | — |
+| `I` | You would not expect this if the hypothesis were true | The synthetic iOS Safari checkout test passes every run |
+| `II` | This could hardly happen if the hypothesis were true | Payment SDK error rate on iOS Safari is flat across the release |
+
+Rules:
+
+- **Rate across a row.** Finish one piece of evidence against every hypothesis before the next.
+- **Rate the evidence as reported,** then use the weight for how far you trust it. Don't
+  hedge a rating to `N` because the source is weak.
+- **Absences are evidence.** "No rise in support tickets" is `I` for any hypothesis that
+  says customers hit an error.
+- **Timing is rarely diagnostic.** "It started right after X" is `C` for X and for anything
+  else that changed that day. List the other changes.
+
+## Weighting
+
+The weight is credibility × relevance, kept coarse:
+
+| Weight | Typical source |
+|---|---|
+| 2 | A primary system record (payment ledger, server logs, a controlled test) that bears directly on the question |
+| 1 | A reliable secondary source or a dashboard whose definition you know |
+| 0.5 | Hearsay, a single anecdote, a dashboard whose definition changed, or evidence only loosely related |
+
+Say why for any weight other than 1. If you can't say, use 1.
+
+## Diagnosticity
+
+A piece of evidence is **diagnostic** when it is rated differently for different hypotheses.
+Evidence rated the same for all of them (all `C`, or a mix of `C` and `N` that adds no
+inconsistency) can't move the ranking, however convincing it feels. These rows are the trap
+ACH exists to expose: they are usually the reasons people give for the favourite hypothesis.
+
+## Linchpins and sensitivity
+
+A linchpin is a row whose removal changes which hypothesis ranks first. For each one:
+
+- Where did it come from, and could it be wrong, out of date, or measured differently?
+- Was it rated right? Re-read the row with a sceptic's eye.
+- What's the cheapest way to confirm it?
+
+If the conclusion rests on a linchpin you can't confirm, report the ranking as a lead.
+
+## Confidence words
+
+Use one word and give the reason:
+
+- **High:** the leader has no `I` or `II` from weight-2 evidence, the runner-up has several,
+  and no single row decides it.
+- **Moderate:** the leader is clearly ahead, but rests on one or two linchpins, or the
+  evidence is mostly weight 1.
+- **Low:** a tie, a gap of 1 or less, or a ranking that flips when one weak row is removed.
+
+## Failure modes
+
+- **Too few hypotheses.** A matrix with two rivals mostly confirms the one you started with.
+- **Hypotheses that aren't exclusive.** If two can both be true, say so; the matrix then shows
+  which one has less against it, not that the other is false.
+- **Evidence that is really an inference** ("the release was buggy"). Break it down to what
+  was observed.
+- **Deception or missing data.** If a source could be biased or the data is incomplete, add a
+  row for the gap and weight the source down.
+
+## When ACH is the wrong tool
+
+- The cause is already confirmed by a direct test. Write it up instead.
+- The question is about choosing a future option. Use a weighted comparison.
+- There is almost no evidence. Plan the research first; a matrix of guesses ranks guesses.

skilldrop_cli/data/packs/research/skills/hypothesis-comparison/scripts/ach_matrix.py

@@ -0,0 +1,204 @@
+#!/usr/bin/env python3
+"""Score an analysis-of-competing-hypotheses (ACH) consistency matrix.
+
+Reads a CSV with one row per piece of evidence and one column per hypothesis,
+and writes a markdown report that:
+  - ranks hypotheses by weighted inconsistency (lowest first), because the
+    hypothesis with the least evidence against it survives, not the one with
+    the most evidence for it
+  - marks each piece of evidence diagnostic or non-diagnostic (it is
+    non-diagnostic when it adds the same inconsistency to every hypothesis,
+    for example C for all, or a mix of C, CC and N)
+  - runs a sensitivity check: drops each piece of evidence in turn and reports
+    the ones whose removal changes which hypothesis ranks first
+
+CSV columns:
+    id        optional, short label such as E1 (default: row number)
+    evidence  required, one line describing the observation
+    weight    optional, a number > 0 for credibility x relevance (default 1)
+    <H...>    one column per hypothesis, each cell one of:
+              CC  very consistent      C  consistent
+              N   neutral               NA not applicable
+              I   inconsistent          II very inconsistent
+
+Scoring: I counts 1 x weight, II counts 2 x weight, everything else 0.
+Consistent ratings are shown but never lower a score.
+
+Usage:
+    python3 ach_matrix.py matrix.csv
+    python3 ach_matrix.py matrix.csv -o ach-report.md
+
+Exit codes: 0 report written, 2 bad input.
+"""
+
+import argparse
+import csv
+import sys
+from pathlib import Path
+
+RATINGS = {"CC": 0, "C": 0, "N": 0, "NA": 0, "I": 1, "II": 2}
+RESERVED = {"id", "evidence", "weight"}
+
+
+def fail(msg):
+    sys.stderr.write("error: " + msg + "\n")
+    sys.exit(2)
+
+
+def fmt(x):
+    return str(int(x)) if float(x).is_integer() else "{:.2f}".format(x).rstrip("0").rstrip(".")
+
+
+def load(path):
+    p = Path(path)
+    if not p.is_file():
+        fail("file not found: " + str(path))
+    with p.open(newline="", encoding="utf-8-sig") as f:
+        reader = csv.DictReader(f)
+        if not reader.fieldnames:
+            fail("the CSV is empty")
+        fields = [h.strip() for h in reader.fieldnames]
+        lower = [h.lower() for h in fields]
+        if "evidence" not in lower:
+            fail("the CSV needs an 'evidence' column")
+        hyps = [h for h in fields if h.lower() not in RESERVED and h]
+        if len(hyps) < 2:
+            fail("the CSV needs at least two hypothesis columns; ACH compares rivals")
+        rows = []
+        for i, raw in enumerate(reader, start=1):
+            row = {(k or "").strip(): (v or "").strip() for k, v in raw.items()}
+            lrow = {k.lower(): v for k, v in row.items()}
+            ev = lrow.get("evidence", "")
+            if not ev:
+                fail("row {}: the evidence cell is empty".format(i + 1))
+            rid = lrow.get("id") or "E{}".format(i)
+            w_raw = lrow.get("weight") or "1"
+            try:
+                w = float(w_raw)
+            except ValueError:
+                fail("row {} ({}): weight {!r} is not a number".format(i + 1, rid, w_raw))
+            if w <= 0:
+                fail("row {} ({}): weight must be greater than 0".format(i + 1, rid))
+            ratings = {}
+            for h in hyps:
+                r = row.get(h, "").upper()
+                if r not in RATINGS:
+                    fail("row {} ({}), column {!r}: rating {!r} is not one of CC, C, N, NA, I, II".format(
+                        i + 1, rid, h, row.get(h, "")))
+                ratings[h] = r
+            rows.append({"id": rid, "evidence": ev, "weight": w, "ratings": ratings})
+    if not rows:
+        fail("the CSV has a header but no evidence rows")
+    ids = [r["id"] for r in rows]
+    dup = sorted(set(x for x in ids if ids.count(x) > 1))
+    if dup:
+        fail("duplicate evidence ids: " + ", ".join(dup))
+    return hyps, rows
+
+
+def scores(hyps, rows):
+    s = {h: 0.0 for h in hyps}
+    for r in rows:
+        for h in hyps:
+            s[h] += RATINGS[r["ratings"][h]] * r["weight"]
+    return s
+
+
+def ranking(hyps, s):
+    # Stable: ties keep the CSV column order.
+    return sorted(hyps, key=lambda h: s[h])
+
+
+def leaders(hyps, s):
+    best = min(s.values())
+    return [h for h in hyps if s[h] == best]
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Score an ACH consistency matrix.")
+    ap.add_argument("matrix", help="CSV: id, evidence, weight, then one column per hypothesis")
+    ap.add_argument("-o", "--output", help="write the report here instead of stdout")
+    args = ap.parse_args()
+
+    hyps, rows = load(args.matrix)
+    s = scores(hyps, rows)
+    order = ranking(hyps, s)
+    top = leaders(hyps, s)
+
+    out = ["# ACH matrix: " + Path(args.matrix).name, ""]
+    out.append("{} hypotheses · {} pieces of evidence · ranked by weighted inconsistency, lowest first".format(
+        len(hyps), len(rows)))
+    out.append("")
+
+    out.append("## Ranking")
+    out.append("")
+    out.append("| Rank | Hypothesis | Inconsistency score | I | II | C or CC |")
+    out.append("|---|---|---|---|---|---|")
+    for h in order:
+        # Ties share a rank (1, 1, 3), so a tie never looks like a lead.
+        i = 1 + sum(1 for x in hyps if s[x] < s[h])
+        n_i = sum(1 for r in rows if r["ratings"][h] == "I")
+        n_ii = sum(1 for r in rows if r["ratings"][h] == "II")
+        n_c = sum(1 for r in rows if r["ratings"][h] in ("C", "CC"))
+        out.append("| {} | {} | {} | {} | {} | {} |".format(i, h, fmt(s[h]), n_i, n_ii, n_c))
+    out.append("")
+    if len(top) > 1:
+        out.append("**Tie for first:** " + ", ".join(top) +
+                   ". The evidence so far does not separate them; find an observation rated differently for each.")
+    else:
+        runner = order[1]
+        gap = s[runner] - s[top[0]]
+        out.append("**Least contradicted:** {} (score {}), {} ahead of {}.".format(
+            top[0], fmt(s[top[0]]), fmt(gap), runner))
+    out.append("")
+
+    out.append("## Evidence")
+    out.append("")
+    out.append("| Id | Evidence | Weight | " + " | ".join(hyps) + " | Diagnostic? |")
+    out.append("|---|---|---|" + "---|" * len(hyps) + "---|")
+    non_diag = []
+    for r in rows:
+        vals = [r["ratings"][h] for h in hyps]
+        # Diagnostic means the item changes the scores differently per hypothesis.
+        diag = len(set(RATINGS[v] for v in vals)) > 1
+        if not diag:
+            non_diag.append(r["id"])
+        out.append("| {} | {} | {} | {} | {} |".format(
+            r["id"], r["evidence"], fmt(r["weight"]), " | ".join(vals), "yes" if diag else "no"))
+    out.append("")
+    if non_diag:
+        out.append("**Non-diagnostic:** " + ", ".join(non_diag) +
+                   ". These count the same against every hypothesis, so they cannot help you choose. "
+                   "Keep them for completeness; don't cite them as support.")
+        out.append("")
+
+    out.append("## Sensitivity: evidence the conclusion rests on")
+    out.append("")
+    linchpins = []
+    for r in rows:
+        rest = [x for x in rows if x is not r]
+        s2 = scores(hyps, rest)
+        top2 = leaders(hyps, s2)
+        if top2 != top:
+            linchpins.append((r, top2))
+    if linchpins:
+        out.append("Dropping any one of these changes which hypothesis ranks first. Check each one's source "
+                   "and how it was rated before you rely on the ranking.")
+        out.append("")
+        for r, top2 in linchpins:
+            out.append("- **{}** ({}): without it, first place is {}".format(
+                r["id"], r["evidence"], " and ".join(top2) + (" (tie)" if len(top2) > 1 else "")))
+    else:
+        out.append("No single piece of evidence changes first place when removed.")
+    out.append("")
+
+    report = "\n".join(out)
+    if args.output:
+        Path(args.output).write_text(report, encoding="utf-8")
+        sys.stdout.write("wrote {} — first: {}\n".format(args.output, ", ".join(top)))
+    else:
+        sys.stdout.write(report)
+
+
+if __name__ == "__main__":
+    main()

skilldrop_cli/data/packs/research/skills/hypothesis-comparison/templates/hypothesis-comparison.md

@@ -0,0 +1,61 @@
+# Competing hypotheses: {observation, in a few words}
+
+_Prepared {YYYY-MM-DD} · Evidence as of {date} · Method: analysis of competing hypotheses_
+
+## Observation
+
+{One sentence: what happened, when, and how big. Example: "Mobile checkout conversion fell 18%
+from Tue 8 Sep, against a flat four-week baseline."}
+
+## Assumptions to confirm first
+
+- [assumption] {anything inferred rather than given, most important first}
+
+## Hypotheses
+
+| Id | Hypothesis | Could be true alongside |
+|---|---|---|
+| H1 | {one sentence that could be false} | {other ids, or "none"} |
+| H2 | … | … |
+| H3 | … | … |
+| H4 | {the measurement hypothesis: tracking, definitions, sampling} | … |
+
+## Evidence and matrix
+
+Ratings: CC very consistent · C consistent · N neutral · NA not applicable · I inconsistent · II very inconsistent.
+Weight: 2 primary record · 1 reliable · 0.5 weak or loosely related.
+
+| Id | Evidence (source) | Weight | H1 | H2 | H3 | H4 | Diagnostic? |
+|---|---|---|---|---|---|---|---|
+| E1 | {observation} ({source}) | 1 | C | N | I | N | yes |
+
+{One line for each weight that isn't 1, saying why.}
+
+## Ranking
+
+| Rank | Hypothesis | Inconsistency score |
+|---|---|---|
+| 1 | … | … |
+
+{Script output or hand arithmetic. Ranked by inconsistency, lowest first.}
+
+## What the ranking rests on
+
+- **Diagnostic evidence:** {ids, and what each separates}
+- **Non-diagnostic evidence, set aside:** {ids, and why they felt persuasive}
+- **Linchpins:** {ids whose removal changes first place, where each came from, and how to confirm it}
+
+## Conclusion
+
+**{Leader}** is the least contradicted explanation. Confidence: **{high / moderate / low}**,
+because {reason in one sentence}.
+
+What would rule out each survivor:
+
+- {H?}: {the observation that would rate it I or II}
+
+## Next observation
+
+| Check | H{a} predicts | H{b} predicts | Who | How long |
+|---|---|---|---|---|
+| {what to look at} | {result} | {result} | {team or role} | {estimate} |

skilldrop_cli/data/packs/research/skills/hypothesis-comparison/templates/matrix.csv

@@ -0,0 +1,4 @@
+id,evidence,weight,H1 short name,H2 short name,H3 short name,H4 measurement
+E1,One observation with its source,1,C,N,I,N
+E2,An absence: something expected under a hypothesis that did not happen,1,I,N,N,C
+E3,[assumption] An assumption the analysis depends on,0.5,N,C,N,N