Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
50 lines (34 loc) · 3.74 KB

CONTRIBUTING.md

File metadata and controls

50 lines (34 loc) · 3.74 KB
Raw

Contributing

This is a research-methodology side project maintained part-time. Contributions are welcome — please calibrate expectations on response time.

Reporting issues

Most useful: a concrete, minimal reproduction.

  • Which skill (meta-analysis / systematic-review / review-methodology-foundations / academic-ref-check / manuscript-typeset) and which stage (e.g., L9.5 heterogeneity, SP4 extraction gate).
  • Your agent (Claude Code / Codex / other) and, for R failures, sessionInfo() plus the package versions (metafor, robumeta, clubSandwich, …).
  • The shortest input that triggers it, and what you expected vs. what you got. A screenshot of the audit card helps for rendering issues.

Issues without a reproduction are harder to act on and may sit longer.

Proposing a change

Open an issue first to check fit before writing code. The scope is deliberately narrow: a supervised, publication-grade evidence-synthesis pipeline for agents. Things that fit:

  • Methodology corrections grounded in a citable source (Cochrane Handbook, Cochrane/Campbell methods papers, PRISMA / GRADE / AMSTAR / JARS updates) — include the citation.
  • New or corrected R paths (with a regression test under the relevant skill's tests/).
  • Bug fixes to the engines (audit_parse.R, signoff_preflight.py, compute_kappa_icc.R, egger_mlma.R, verify_http.py, ingest_search_exports.py).
  • Audit-card narrative/voice improvements that keep the pixel gate green and the numbers/flags unchanged.

Things that don't fit:

  • Anything that softens a red light or weakens a sign-off gate. Red lights are computed by R and gate downstream work on purpose; "make it pass" is not a feature.
  • Fabricating data, citations, or statistics to make a demo look complete.
  • General-purpose stats features unrelated to evidence synthesis.

Pull requests

  • One concern per PR.
  • Touch only the skill you mean to. The five skills have explicit ownership boundaries; the shared base (review-methodology-foundations) is consumed by reference, not copy-pasted into consumers.
  • Run the relevant tests before submitting (these are exactly what CI runs — see .github/workflows/ci.yml):
    • R regression: Rscript skills/meta-analysis/tests/test_all_scripts.R (point META_SKILL_DIR at the repo's skills/meta-analysis if not deployed).
    • Python suites (each is a standalone script that exits non-zero on failure; engine-gated tests self-SKIP when pandoc / xelatex / Rscript are absent, so a missing engine never reds them):
      • Sign-off + reconciliation engines: python3 skills/review-methodology-foundations/scripts/test_signoff_preflight.py and test_registration_reconcile.py.
      • Ingestion / full-text validators: the test_*.py files under skills/systematic-review/scripts/.
      • Figure renderers: python3 skills/meta-analysis/scripts/plots/tests/run_tests.py.
      • manuscript-typeset: test_fidelity.py, test_strip.py, test_pdf.py, test_docx.py under skills/manuscript-typeset/scripts/tests/.
    • Audit-card renderer: node tests/test_s6_payload.mjs (a hard smoke, no browser) plus the Node tests under skills/meta-analysis/scripts/tests/ (npm install first).
  • Match the surrounding style. Keep methodology claims cited.

Methodology disagreements

Disagreements about statistical method (which τ² estimator, when Egger is valid, how to treat dependent effect sizes) are welcome — bring the citation. The standing rule across this project: empirical evidence beats theoretical concern, and nothing ships that pretends a result is more certain than the data supports.

Response time

Triage typically lands within a week or two; review of changes that touch the statistical engines may take longer. A polite bump after a month of silence is fine.