develop-contribution

Develop Contribution

Create or regularize one contributions/<slug>/ folder: badge-general compliant, self-contained, with a report/report.tex detailed enough that paper writing never needs to re-read the code.

Read First

• contributions/README.md — the badge-general contract
• survey/survey.pdf, gaps section — when positioning a new contribution
• references/methodology.md — evaluation, statistics, figure discipline
• references/experiments.md — run logs and autonomous campaigns
• references/reproduction.md — reproducing external work
• references/ethics.md — data red flags
• references/data.md — data placement and inter-contribution data

dependencies (when the contribution has shared/large data or consumes another contribution's output)

Before Building (both modes)

Fill the Positioning section of the contribution README:

• the claim this contribution will support
• the delta vs the nearest prior work (cite survey/SOTA citekeys)
• the evidence plan: what will be measured or collected, and how
• the falsifiability condition: what outcome would refute the claim

If the claim has no evidence path, stop and discuss with the user.

Create Mode

1. Copy contributions/_template/ to contributions/<slug>/ (kebab-case

slug).

1. Python code? Write the contribution's own pyproject.toml (name,

requires-python, dependencies), add "contributions/<slug>" to [tool.uv.workspace] members in the root pyproject.toml, run uv sync --all-packages from the root (plain uv sync prunes the members' dependencies on a package = false root). Genuinely conflicting dependencies → move the path to exclude, create a local venv, document it in the README.

1. Develop inside the folder — free-form structure (src/, data/,

figures/, outputs/, notebooks). Follow references/methodology.md for any evaluation; keep a run log per references/experiments.md for every run that supports a claim, including autonomous campaigns. For reproductions of external work, follow references/reproduction.md.

1. Fill the README badge checklist truthfully — every checked box has

evidence inside the folder. Check data against references/ethics.md.

1. Write report/report.tex: motivation, positioning vs the SOTA (cite the

root .bib), method, setup, results with figures/tables, limitations. Build it: make contribution C=<slug>.

1. Run make check.

Regularize Mode

1. Inventory the draft folder: what exists, what it claims, what is missing

against the badge checklist.

1. Reorganize in place — keep provenance (note original filenames when

renaming), capture the environment, verify the run path works end-to-end, record data provenance and ethics flags.

1. Continue with Create Mode steps 4–6.

Rules

• Self-contained: no imports from other contributions; tooling worth

sharing becomes its own contribution referenced in the README. If the input is another contribution's output, declare it and read it in place — never copy (see references/data.md).

• Exploratory results never masquerade as confirmed evidence — label them.
• Negative results are results: report them in report.tex.

Done When

• Badge checklist fully and truthfully checked, report.pdf built,

workspace coherent, make check passes