hsigstad /questions — Populate docs/questions.md
Draft or maintain a project's docs/questions.md: the small set of
policy-relevant questions the research answers. Each question aggregates
evidence from multiple hypotheses and maintains a current working answer
that evolves as new results come in.
These are synthesis questions — the "so what?" that motivates the paper and frames the contribution. They sit above the hypothesis layer: hypotheses are testable predictions; questions are what the predictions collectively tell us.
What questions.md is NOT
- Not a staging area for half-formed ideas (that's
thinking.md) - Not a list of descriptive queries ("what share of cases have X?")
- Not a restatement of hypotheses (those have their own doc)
- Not a research agenda (keep it to what THIS project answers)
Arguments
/questions— infer project from CWD/questions <project-slug>— run against a specific project/questions --update <Q:slug> [--artifact <path>]— update one question's working answer after new evidence (e.g., from/connect-results)/questions --audit— check for stale answers, missing hypothesis refs, orphan questions with no tested hypotheses/questions --extend— propose a new question (requires justification)
Finding the workspace root
The workspace root contains CLAUDE.md alongside projects/, pipelines/,
ideas/, research/. If inside a project, search upward. $ROOT for paths;
$PROJ = $ROOT/projects/<slug>/.
What to read
$PROJ/CLAUDE.md— current focus$PROJ/docs/summary.md— the main research question (required)$PROJ/docs/questions.md— existing questions (if any; match template)$PROJ/docs/hypotheses.md— all hypotheses with evidence strengths$PROJ/docs/findings.md— empirical results (if exists)$PROJ/docs/reference/analysis-index.yaml— what's been tested (if exists)
Do NOT read theory.md, literature.md, institutions.md unless a specific question's answer needs institutional context. Questions synthesize from hypotheses, not from primary sources.
Entry template
Each question follows this structure:
### Q:<slug>: <Question in natural language?>
**Relevant hypotheses:** H:<slug1>, H:<slug2>, ...
**Current working answer:**
<2-5 sentences synthesizing what the tested hypotheses tell us.
Cite specific numbers from results. Note where evidence is strong
vs suggestive. Write as you would for a non-specialist.>
**Open:** <What remains untested or ambiguous. Reference specific
H: slugs with their status (not tested / queued / interpreted).>
Conventions
Slugs
Each question has a stable slug prefixed with Q: (e.g.,
Q:does-favoritism-exist, Q:how-circumvented). Slugs are:
- Lowercase, hyphenated, 2-5 words
- Unique within the project
- Never renamed once created (same stability rule as H: slugs)
- Used for cross-referencing in analysis files, index tags, and prose
Scope
- Aim for around 5 questions per project. This is a soft limit — adding a 6th or 7th is fine if genuinely warranted, but each new question should pass the bar: "would a policymaker or seminar audience ask this?" If not, it's probably a hypothesis or a thinking.md note, not a research question.
- Questions must be answerable (at least partially) by the project's data and design. Aspirational questions belong in thinking.md.
- Questions should be policy-relevant or have clear "so what?" value. Pure mechanism questions ("through which channel?") are fine if the channel has policy implications.
Working answers
- Write for a non-specialist. No jargon, no regression notation.
- Cite specific numbers from results (coefficients, percentages).
- Be honest about uncertainty. "The evidence suggests..." not "We have shown..."
- Update after each
/connect-results(or equivalent) run that changes the evidence base for any relevant hypothesis. - Date-stamp is NOT needed — git history tracks when answers changed.
Relationship to other docs
- summary.md states the main research question in 1-2 sentences. questions.md decomposes it into answerable sub-questions.
- hypotheses.md contains the testable predictions. questions.md groups them and synthesizes their answers.
- findings.md records individual empirical results. questions.md interprets what they mean collectively.
- thinking.md holds open-ended speculation. When a thinking.md note matures into something the project can answer, it may become a question. Most won't.
Draft protocol (new file)
- Read summary.md to identify the paper's core motivation.
- Read hypotheses.md to understand what's testable.
- Identify 3-5 questions that a seminar audience or policymaker would ask, such that the hypotheses collectively address them.
- For each question: list the relevant H: slugs, draft a working answer from current evidence, note what's still open.
- Present the list to the user for confirmation before writing.
Update mode (--update Q:<slug>)
Surgical edit of one question's working answer. Triggered when new
evidence arrives (typically after /connect-results interprets a
returned analysis).
Minimal read set:
$PROJ/docs/questions.md— locate the target entry$PROJ/docs/hypotheses.md— read the updated hypothesis/hypotheses- The triggering analysis file (if referenced)
What to edit: Only the target question's Current working answer
and Open sections. Do not touch other questions.
Output: The edited questions.md plus a one-sentence summary of what changed in the working answer.
Audit mode (--audit)
Check without writing:
- Every H: slug referenced in questions.md exists in hypotheses.md
- Every question has at least one hypothesis with evidence strength above "Not tested"
- Working answers are consistent with current evidence strengths in hypotheses.md (e.g., don't claim "strong evidence" if all relevant hypotheses say "Moderate" or "Weak")
- No orphan questions (all hypotheses mapped to at least one question) — orphan hypotheses are fine (not every test maps to a big question)
Report findings as a bulleted list.
Integration with other skills
/connect-resultsshould suggest a/questions --updatewhen an interpreted result changes the evidence base for a question/nextproposal mode can reference open items in questions.md/hypothesis --updateshould note if the change affects a question's working answer