hypothesis

Files (2)

• SKILL.md
• entry-format.md · reference/

SKILL.md (first lines)

# /hypothesis — Populate docs/hypotheses/

Draft or extend a project's `docs/hypotheses/` folder (or a legacy flat
`docs/hypotheses.md`): a structured mapping of theoretical predictions to pre-existing
evidence and concrete empirical tests the project can run. Each
hypothesis is a single testable claim with its theory, evidence,
specification, and data requirement spelled out.

## Locating the hypotheses doc

Discovery order, first hit wins:

1. `$PROJ/docs/hypotheses/index.md` (folder mode — default)
2. `$PROJ/docs/hypotheses.md` (flat file — legacy)

If neither exists, create **folder mode** (`docs/hypotheses/`, `index.md` + one
file per hypothesis) regardless of entry count — it is the default per
`project_docs_contract.md` §5 and matches the sibling `docs/findings/` layout.
The flat file is **legacy**: keep maintaining existing `docs/hypotheses.md`
files, but do not create new ones — migrate them to a folder when convenient
(see "Folder mode" below).

## Arguments

- `/hypothesis` — infer project from the current working directory.
- `/hypothesis <project-slug>` — run against a specific project under `projects/`.
- `/hypothesis --audit` — do not write; report gaps, dangling refs, and orphan theories.
- `/hypothesis --extend` — preserve existing entries; only append new hypotheses suggested by current evidence/literature.
- `/hypothesis --update <H#> [--artifact <AN-id-or-build-path>]` — **surgical single-entry edit**. Update the status block (or evidence/test fields) of one existing hypothesis after a new analysis result. Reads only `CLAUDE.md`, `hypotheses.md`, and the optional triggering artifact. `--artifact` accepts either an AN id (preferred — e.g. `AN-019`; the skill reads `docs/analyses/an-019-*.md` to recover script + target + headline + confidence) or a raw `build/<path>` (fallback for unledgered runs). Does not re-derive other hypotheses, does not re-read `theory.md`/`literature.md`/etc. Use from `/next` step 5 when a run affects exactly one hypothesis (demotion after null, strengthening after a confirming test, status-block refresh).

## Finding the workspace root

The workspace root contains `CLAUDE.md` alongside `projects/`, `pipelines/`, `ideas/`, `research/`. If the current directory is inside a project, search upward to find the root. Use `$ROOT` for all paths below. The project root is `$ROOT/projects/<slug>/` — use `$PROJ` for it.

## What to read (in order)

Read these files to build context. If one is missing, note it and move on; never invent its content.

1. `$PROJ/CLAUDE.md` — current focus, key terms, conventions
2. `$PROJ/docs/summary.md` — research question (required)
3. `$PROJ/docs/thinking.md` — candidate angles, open questions
4. `$PROJ/docs/theory.md` — formal frameworks; every hypothesis should link to at least one framework here. If missing, suggest running `/theory` first.
5. `$PROJ/docs/literature.md` — empirical literature the paper cites or positions against. Hypotheses should be aware of what's already known.
6. `$PROJ/docs/institutions.md` — institutional facts (rules, actors, timelines)
7. `$PROJ/docs/data.md` — what variation/outcomes are available. Hypotheses without a data home get cut or flagged.
8. `$PROJ/docs/methods.md` (if exists) — identification strategy details
9. `$PROJ/docs/hypotheses.md` or `$PROJ/docs/hypotheses/index.md` (if exists) — existing hypotheses; match their template exactly and preserve content
10. `$PROJ/paper/main.tex` §introduction, §hypotheses, §empirical if present
11. `$PROJ/paper/*.bib` — existing bibliography
12. `$PROJ/references/reports/**`, `$PROJ/references/pdfs/**` — technical/policy reports (scan titles; read the 3–5 most relevant in full)
13. `$PROJ/references/news/stories.csv` — anecdotal evidence; sample the full text of 5–10 rows most relevant to each candidate hypothesis via `texts/NNN.txt`
14. Project-specific evidence files (e.g., `$PROJ/docs/scheme_evidence.md` in procure) — scan for existing evidence a hypothesis can cite

## Decide the template

If `docs/hypotheses.md` already exists: infer its template from the current entries. **Match it exactly** — same section headers, same ordering of fields, same prose style. Do not reformat existing content.

If it does not exist, offer the user three templates:

- **Tiered by evidence strength** (saude-style): group by `## Tier 1: Very Strong Pre-Existing Evidence`, `## Tier 2: Strong, Directly Testable`, `## Tier 3: Plausible, Partially Testable`. Each entry: Theory → Prediction → Pre-existing evidence (bulleted with sources) → Evidence strength + justification → Empirical test → Data → Priority. Best when there's a rich pre-existing empirical literature to assess against.
- **Clustered by paper section** (procure-style): group by `## Cluster A: ...`, mapping each cluster to a paper section. Each entry: Statement (bold sentence) → Theoretical motivation (paragraph with refs) → Case evidence (paragraph with refs) → Empirical test (outcome / variation / specification / fixed effects) → Data requirements and limitations. Best when hypotheses map cleanly to distinct paper sections with concrete empirical specs.
- **Exploration-first**: group by candidate angle from thinking.md. Each angle gets 2–4 hypotheses with a looser template (Prediction → Why it matters → What evidence already exists → How we'd test it → What data we'd need). Best for early-stage projects without a fixed research question.

For early-stage projects (summary.md says "research question not yet fixed" or equivalent), default to **exploration-first**.

## Draft protocol

1. Build a **hypothesis candidate list**. For each framework in theory.md (or each mechanism in the relevant literature if theory.md is missing), enumerate the directional predictions that the project's data could adjudicate. For each candidate, record: short name, theory ref, prediction (1 sentence), variable(s) it touches.
2. Filter aggressively. Drop candidates where (a) no variation in the project's data can identify the prediction, (b) the prediction is already established well enough in the literature that another test adds nothing, or (c) two candidates collapse into the same empirical spec — keep the tighter framing.
3. For each surviving hypothesis, draft the entry matching the chosen template. If the project's existing entries have a `**Slug:**` field, assign a slug to each new entry (lowercase, hyphenated, 2-4 words, e.g., `value-interaction`, `recusal-selective`). Slugs must be unique and stable — they are used as identifiers in analysis tracking systems. For each field:
   - **Theory / Theoretical motivation**: name the framework from theory.md (by number or name). If the theory isn't in theory.md, either add a stub there or write `[theory: {author year} — not yet in theory.md]`.
   - **Prediction / Statement**: directional and specific. "Higher X causes higher Y in subgroup Z" beats "X is related to Y."
   - **Pre-existing evidence / Case evidence**: every bullet must cite a specific source. Sources can be:
     - A news row: `[stories.csv #NNN]` with a short description
     - A report: `[{filename.pdf}, p. N]`
     - A lit entry: `[Author Year]` where the entry exists in literature.md or paper/*.bib
     - An institutional fact: `[institutions.md §N]`
     - Never cite from memory — only from materials actually in the project.
   - **Evidence strength**: rate honestly (Very strong / Strong / Moderate / Weak) and justify in one sentence. If mixed, say so.
   - **Empirical test**: specify the concrete specification — outcome variable, source of variation, the statistical form (OLS / IV / event study / density test / etc.), fixed effects. Reference data.md for data sources.
   - **Data requirements / limitations**: name datasets and flag any the project does not yet have access to. Note threats to identification.
   - **Priority** (if template includes it): rank by (evidence strength) × (testability with current data) × (distinctiveness — does this test something no one else can?).
4. Aim for **8–14 hypotheses**. More means insufficient filtering. Fewer than 6 means the project is under-developed or the filtering was too aggressive.
5. If the template includes a summary table, write it after all entries. It should make the whole hypothesis space scannable in one screen.

## Folder mode (`docs/hypotheses/`)

Folder mode is the default: `docs/hypotheses/` with `index.md` (intro + field
schema + cluster index + summary table) and one `<slug>.md` per hypothesis,
named by the slug field (no numeric prefixes). Each per-hypothesis file is a
self-contained mini-document: intro, a `> **Evidence strength: …**` verdict
callout (auto-styled by sitekit — lead the clause so the color bucket is
unambiguous), then Theory / Prediction / Competing prediction(s) / Prior
research / Evidence table (AN-id rows) / Open tests, in prose. Keep it under
~150 lines; if it grows past that the hypothesis is probably two.

The full per-hypothesis template, the verdict-callout color rules, style notes,
path conventions, and per-mode folder behavior are in
[`reference/entry-format.md`](reference/entry-format.md) — **read it before
creating or editing entries.**

## Guardrails

- **Cite only real references.** If a citation isn't in literature.md, paper/*.bib, or an existing doc, write `[ref needed: ...]` — placeholders are fine, invented refs are not. Don't name-drop Kleven/Pomeranz/Galanter because they sound apt; cite only what the paper actually uses.
- **Source every evidence claim.** Every "pre-existing evidence" bullet ends with a bracketed source pointer; "X is well-documented" without one isn't evidence — source it or drop it.
- **Testable with project data.** If `docs/data.md` has no source that can measure the outcome and variation, refine the hypothesis to fit, flag `[requires: dataset X — not yet accessed]`, or drop it. "Firms respond strategically to enforcement" is unmeasurable; "firms close the targeted CNPJ within 18 months of an execução fiscal filing" is testable.
- **Theory-backed.** Every hypothesis links a theory.md entry or a formal citation. "We expect X" without theory is a prior, not a hypothesis — cut it.
- **Preserve existing content.** Read `docs/hypotheses.md` first; in extend/normal mode append rather than rewrite existing entries, marking new ones with a `Status: drafted YYYY-MM-DD` line.
- **No padding.** If a section would be generic, leave it empty with a brief TODO.
- **Honest tier assignment.** Tier reflects *existing* evidence, not the paper's ambition — don't push a weakly-supported hypothesis into Tier 1 because it's the central claim.
- **Don't transplant across projects.** Hypotheses from saude or procure don't carry over; each project's are grounded in its own evidence and data.

## Output protocol

1. Print a short preview: hypothesis numbers + short names + one-line predictions, grouped by tier/cluster. Flag any `[ref needed]`, `[theory: not yet in theory.md]`, or `[requires: ...]` placeholders.
2. If more than 3 placeholders appear, pause and ask the user whether to proceed, revise inputs first, or run `/theory` and `/literature` first.
3. Wait for confirmation unless the user said "go ahead."
4. Write `docs/hypotheses.md`. Read first if it exists; merge by appending, never rewriting.
5. Report back: number of hypotheses drafted, number of placeholders, path to the file. Cross-reference theory.md (which frameworks were used, which were orphaned).

From hsigstad/research-kit, MIT.

More from hsigstad/research-kit