empirical-workflow

Files (92)

• SKILL.md
• canon.md · methods/causal-design/
• details.md · methods/causal-design/
• method.manifest.yaml · methods/causal-design/
• prompt.md · methods/causal-design/
• references.bib · methods/causal-design/
• shared-rules.md · methods/causal-design/
• template.R · methods/causal-design/
• canon.md · methods/conjoint/
• details.md · methods/conjoint/
• method.manifest.yaml · methods/conjoint/
• prompt.md · methods/conjoint/
• template.R · methods/conjoint/
• canon.md · methods/did/
• details.md · methods/did/
• method.manifest.yaml · methods/did/
• prompt.md · methods/did/
• template.R · methods/did/
• canon.md · methods/field-experiment/
• details.md · methods/field-experiment/
• method.manifest.yaml · methods/field-experiment/
• prompt.md · methods/field-experiment/
• template.R · methods/field-experiment/
• canon.md · methods/fixed-effects/
• details.md · methods/fixed-effects/
• method.manifest.yaml · methods/fixed-effects/
• prompt.md · methods/fixed-effects/
• template.R · methods/fixed-effects/
• canon.md · methods/iv/
• details.md · methods/iv/
• method.manifest.yaml · methods/iv/
• prompt.md · methods/iv/
• template.R · methods/iv/
• canon.md · methods/rdd/
• details.md · methods/rdd/
• method.manifest.yaml · methods/rdd/
• prompt.md · methods/rdd/
• template.R · methods/rdd/
• canon.md · methods/selection-on-observables/
• details.md · methods/selection-on-observables/
• method.manifest.yaml · methods/selection-on-observables/
• prompt.md · methods/selection-on-observables/
• template.R · methods/selection-on-observables/
• canon.md · methods/synthetic-control/
• details.md · methods/synthetic-control/
• method.manifest.yaml · methods/synthetic-control/
• prompt.md · methods/synthetic-control/
• template.R · methods/synthetic-control/
• blindspot-audit.md · references/
• code-review.md · references/
• data-contract.md · references/
• delivery-contract.md · references/
• elite-is-paper-standards.md · references/
• execution-discipline.md · references/
• identification-decision-tree.md · references/
• latex-manuscript-adapter.md · references/
• method-facade-contract.md · references/
• method-governance.md · references/
• operational-quality-loop.md · references/
• outlet-positioning.md · references/
• …and 32 more

SKILL.md (first lines)

# Empirical Workflow

This file is the canonical Empirical Workflow Kit implementation. Runtime views
defined in `workflow.manifest.yaml` link here; edit only the canonical tree.

This skill advances empirical research through question, evidence, and inference.
Documented contracts preserve that reasoning and its provenance. The
repository, not the conversation, is the source of truth. Communicate in the
primary language used in the user's first substantive request, unless the user
explicitly asks to switch, and write durable repository artifacts in English.

## Router

Before selecting a stage, read in this order:

1. `RESEARCH_PROTOCOL.md`.
2. Active `research.yaml`, or `research.example.yaml` when no project
   configuration exists.
3. Project-root `_status.md`.
4. The current or most relevant Evidence card.
5. The tail of `decision-log.md`.

If a required project-state artifact does not yet exist, record that absence in
the next status artifact; do not invent its contents. Use `research.yaml` to
confirm the current stage, approved designs, authority level, languages, and
artifact conventions. Then load only the selected stage file immediately before
performing that stage; do not preload the stage directory.

| Stage | Contract file |
|---|---|
| 1. Dataset infrastructure | `stages/stage1-data-infra.md` |
| 2. Literature map | `stages/stage2-lit-map.md` |
| 3. Theory and hypotheses | `stages/stage3-theory-hypotheses.md` |
| 4. Variables map | `stages/stage4-variables.md` |
| 5. Measurement and validity | `stages/stage5-measurement.md` |
| 6a. Reduced form | `stages/stage6a-reduced-form.md` |
| 6b. Structural | `stages/stage6b-structural.md` |
| 7. Paper writing and review | `stages/stage7-writing.md` |

## Module contract

Before each analysis module, use the existing Evidence card to state the economic
question, why it matters, competing explanations, what is observed, what the
design can distinguish, and the result that would change the judgment. Close
with what was learned, what remains indistinguishable, and whether to continue,
demote to background, narrow/delete, or stop. Before estimation, ask whether even
a successful estimate would yield only a mechanical fact and what knowledge it
would add to this paper. Read `references/execution-discipline.md` for this work-value
and stopping rule. Do not create a new tracker or equate coefficients, prediction
counts, or checkpoint verdicts with knowledge gained.

Description, measurement, institutional accounting, and conditional models are
valid branches. Apply identification obligations to causal claims, not to every
useful finding. Keep internal audit records separate from reader-facing prose.

Before interpreting or writing results in any branch, read
`references/research-writing.md`: question-led organization, economic meaning,
contribution, and behavioral inference apply across all methods. The selected
pack adds technical obligations; it cannot turn its methods paragraph into the
paper's organizing principle or make a passed diagnostic a contribution.

## Mandatory-pause routing

Proceed automatically through routine, reversible work that stays within the
approved design. Pause and request a recorded decision before a material design
change, failed identifying diagnostic, post-result specification, or external
publication or submission. The pause note must name the trigger, affected
artifacts, options, and decision needed to resume. Do not ask for confirmation
before every sub-step.

Changes to the main specification, estimation sample, clustering level, or
identifying strategy always require a Mandatory pause and a `decision-log.md`
entry before execution. A current unresolved exit failure returns work to the responsible stage.
Record whether it remains active, is repaired, closes with claim withdrawal, or
is retained as a disclosed limitation that the remaining claim can bear. Preserve
the failed record and closure evidence; a caveat alone cannot rescue a claim.

## Reference files

Read a reference only when the selected stage calls for it:

- `references/identification-decision-tree.md`: design and estimator choice.
- `references/robustness-checklists.md`: design-specific reader obligations.
- `references/r-standards.md`: R layout and verification helpers. **R is the
  default language for a project's empirical work**; read this before any
  construction, diagnostic, estimation, table or figure work.
- `references/python-standards.md`: Python layout and export rules; read only
  where an exception to the R default has been recorded in `decision-log.md`.
- `references/data-contract.md`: identity and validation contract across a
  language boundary; read when a stage produces, validates, or consumes
  analysis data across one.
- `references/delivery-contract.md`: what `output/` must contain before a
  submission is finished; read at Stage 7 and before Checkpoint C.
- `references/writing-standards.md`: the house prose style, with four advisory pattern checks; read before drafting and before the final pass.
- `references/elite-is-paper-standards.md`: contribution, construct, argument,
  and exhibit discipline for elite IS papers; read in Stages 2, 3, and 7 when
  IS positioning is relevant. The shared research-writing contract applies to all.
- `templates/paper-story-template.md`: contribution-to-evidence planning
  template; complete in Stage 3 and update in Stage 7.
- `references/blindspot-audit.md`: four-quadrant audit and verdict rule.
- `references/latex-manuscript-adapter.md`: Stage 7 LaTeX binding of the
  manuscript to the registry; read only when the format adapter is applied.
- `references/writing-under-the-registry.md`: how to interpret advisory writing checks without turning
  internal records into prose; read when a finding asks you to change prose.
- `references/operational-quality-loop.md`: planning, baseline reproduction,
  progressive validation, debugging, and completion evidence; read before
  changing research scripts, pipelines, validators, or registry logic.
- `references/research-writing.md`: durable prose, effect-interpretation,
  limitation, and quotation rules; read when producing or reviewing research
  prose.
- `references/execution-discipline.md`: work-value, object-inspection,
  verification, parallelism, destructive-action, and scope rules; read when a
  stage plans execution or review.
- `references/method-governance.md`: literature-first method choice,
  source-supplied boundaries, and the pilot/sweep decision rule; read before a
  method, metric, measurement, sample, or inference choice.
- `references/code-review.md`: concise research-code review taxonomy; read
  only when reviewing or simplifying code.
- `references/start-prompts.md`: user-facing autonomous and takeover entry

From bobbyZhong10/empirical-workflow-kit, MIT.

More from bobbyZhong10/empirical-workflow-kit