From 37e5114366e6964af9a6c987083f0d884da60c7d Mon Sep 17 00:00:00 2001 From: Marius Lange Date: Thu, 15 Oct 2026 09:40:28 +0200 Subject: [PATCH 1/4] Review guide: the task README is the one record Agreed deliverables, decisions, PRs and issues in the README; restating it elsewhere and editing an earlier task are findings; findings are checked in the deliverables. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011aQpF4MA9v7dTVK1FqMMVJ --- {{cookiecutter.project_name}}/REVIEW_GUIDE.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/{{cookiecutter.project_name}}/REVIEW_GUIDE.md b/{{cookiecutter.project_name}}/REVIEW_GUIDE.md index bc5f484..8908f5e 100644 --- a/{{cookiecutter.project_name}}/REVIEW_GUIDE.md +++ b/{{cookiecutter.project_name}}/REVIEW_GUIDE.md @@ -40,8 +40,10 @@ where it went and that it was agreed, while moving it is still cheap. ### 3. The task contract -Agent work belongs in a task directory `analysis//.../_vN/` with a `README.md` naming real inputs, -outputs and write-back keys. Outputs go through `task_paths(__file__)` to the task's own `results/`, `reports/`, +Agent work belongs in a task directory `analysis//.../_vN/` whose `README.md` records the +deliverables agreed with the human, real inputs, decisions and who took them, write-back keys, and every PR and +issue the session opened. An edit to an earlier task's directory is a finding: a later version names the one it +follows instead. Outputs go through `task_paths(__file__)` to the task's own `results/`, `reports/`, `figures/`, `outputs/`. Writes to `data//results/` or the central `figures/` are the human lane and are a finding. @@ -50,9 +52,9 @@ unrecorded key can't be traced back, an unsuffixed one collides with the next ve ### 4. Scientific correctness -The point of the repo. Check that the claim in the PR body follows from what the code computes: the right cells, -the right grouping, a control where one is needed, and a comparison not confounded by condition, time point, -sample or batch. A number that reaches a figure is worth more scrutiny than anything below. +The point of the repo. Check that each finding in the deliverables follows from what the code computes: the right +cells, the right grouping, a control where one is needed, and a comparison not confounded by condition, time +point, sample or batch. A number that reaches a deliverable is worth more scrutiny than anything below. ### 5. Reinvention @@ -68,7 +70,8 @@ task is fine. Prose is reviewed like code. READMEs, docstrings, comments and the PR body: no restating the diff, no filler preamble, no exhaustive caveats. Padding rots the same way dead code does, and these docs are load-bearing for -the next agent. +the next agent. Each fact has one home, the task README: a report or PR body that restates it instead of linking +is a finding, because the copies drift. ## Do not report From 5d539316d9f2a56a8d92a61488565fbe5468c435 Mon Sep 17 00:00:00 2001 From: Marius Lange Date: Thu, 15 Oct 2026 10:03:54 +0200 Subject: [PATCH 2/4] Review guide: promotions are recorded in the README, flagged in the PR Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011aQpF4MA9v7dTVK1FqMMVJ --- {{cookiecutter.project_name}}/REVIEW_GUIDE.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/{{cookiecutter.project_name}}/REVIEW_GUIDE.md b/{{cookiecutter.project_name}}/REVIEW_GUIDE.md index 8908f5e..3fe9a0b 100644 --- a/{{cookiecutter.project_name}}/REVIEW_GUIDE.md +++ b/{{cookiecutter.project_name}}/REVIEW_GUIDE.md @@ -35,8 +35,8 @@ A write to a working object goes through `commit_adata`, gated behind a dry run. ### 2. Promotions, which leave no diff `data/` is gitignored, so an object written into `data//processed/` appears nowhere in the diff; the task -README's `Write-back` section is the only trace. The right subdirectory is not guessable. Check that the PR *says* -where it went and that it was agreed, while moving it is still cheap. +README's `Write-back` section is the only trace. The right subdirectory is not guessable. Check that the README +*says* where it went, that the PR body flags it for sign-off and that it was agreed, while moving it is still cheap. ### 3. The task contract From 458fa6cbc64f9a33bf3a917d466e23a01e2034fd Mon Sep 17 00:00:00 2001 From: Marius Lange Date: Thu, 15 Oct 2026 10:43:39 +0200 Subject: [PATCH 3/4] Task PR template; review guide checks what hooks can't The PR template holds a task PR's details; the task README summarizes it. The review guide drops what the plugin's hooks enforce and points to the PR template. AGENTS.md says when to use the gpu environment; the project README links the plugin's data layout instead of restating it. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011aQpF4MA9v7dTVK1FqMMVJ --- .../.github/pull_request_template.md | 30 +++++++++------- {{cookiecutter.project_name}}/AGENTS.md | 3 ++ {{cookiecutter.project_name}}/README.md | 9 ++--- {{cookiecutter.project_name}}/REVIEW_GUIDE.md | 36 +++++++++---------- 4 files changed, 42 insertions(+), 36 deletions(-) diff --git a/{{cookiecutter.project_name}}/.github/pull_request_template.md b/{{cookiecutter.project_name}}/.github/pull_request_template.md index 944e99e..2edff44 100644 --- a/{{cookiecutter.project_name}}/.github/pull_request_template.md +++ b/{{cookiecutter.project_name}}/.github/pull_request_template.md @@ -1,23 +1,29 @@ -## Changes + - +**Task:** : -- ... +## Deliverables -## Bug fixes + - +## Method and decisions -- ... + -## New +| decision | value | by | why | +| --- | --- | --- | --- | +| | | | | - +## Findings -- ... + -## Related issues +## Needs you - + -Closes # +## Related + + diff --git a/{{cookiecutter.project_name}}/AGENTS.md b/{{cookiecutter.project_name}}/AGENTS.md index 0759c3e..5ce31b0 100644 --- a/{{cookiecutter.project_name}}/AGENTS.md +++ b/{{cookiecutter.project_name}}/AGENTS.md @@ -34,3 +34,6 @@ test config. | Run Python | `pixi run python script.py` | | Run tests | `pixi run test` | | Add a conda / PyPI package | `pixi add ` / `pixi add --pypi ` | + +The `gpu` environment (Linux with NVIDIA) adds rapids-singlecell: use it over scanpy for neighbors, UMAP and +clustering on more than about 100k cells, in a GPU job. diff --git a/{{cookiecutter.project_name}}/README.md b/{{cookiecutter.project_name}}/README.md index 23d6b2d..42af25f 100644 --- a/{{cookiecutter.project_name}}/README.md +++ b/{{cookiecutter.project_name}}/README.md @@ -153,12 +153,9 @@ Or edit `pixi.toml` directly and run `pixi install`. 📓 Data and notebook conventions - **Notebook naming**: `[INITIALS]-[YYYY]-[MM]-[DD]_description.ipynb` -- **Data layout** (one folder per dataset, gitignored): - - `data//raw/` — bytes as they arrived; never written by analysis - - `data//resources/` — curated inputs that are not data: gene lists, marker tables - - `data//processed/` — objects code loads to do new work, as AnnData `.zarr` - - `data//results/` — a notebook's own outputs, file names prefixed with the notebook's stem -- **Figures**: `figures//` +- **Data layout and the notebook lane**: the analysis-workflow skill's + [Data](https://github.com/quadbio/analysis-workflow/blob/main/skills/analysis-workflow/SKILL.md#data) and + [Two lanes](https://github.com/quadbio/analysis-workflow/blob/main/skills/analysis-workflow/SKILL.md#two-lanes) - **Import paths** via the local package: ```python diff --git a/{{cookiecutter.project_name}}/REVIEW_GUIDE.md b/{{cookiecutter.project_name}}/REVIEW_GUIDE.md index 3fe9a0b..855d4e4 100644 --- a/{{cookiecutter.project_name}}/REVIEW_GUIDE.md +++ b/{{cookiecutter.project_name}}/REVIEW_GUIDE.md @@ -4,9 +4,8 @@ PR review playbook for **review agents running on GitHub**. Imperative voice. **Scope: review only.** Comment and suggest. Do not push commits or apply fixes. -> Everything above "This repo" comes from the analysis template, which takes it from the analysis-workflow -> plugin; change it there and pull it with `cruft update`. Reviewers cannot load the plugin, which is why this -> copy exists. +> Everything above "This repo" comes from the analysis template; change it there and pull it with `cruft update`. +> It tells reviewers, who cannot load the analysis-workflow plugin, what to check of its rules. The code has usually already run. That is not a reason to lower the bar: requiring a rerun in better shape is a normal outcome. Say what to redo, not just what was wrong. @@ -40,21 +39,19 @@ README's `Write-back` section is the only trace. The right subdirectory is not g ### 3. The task contract -Agent work belongs in a task directory `analysis//.../_vN/` whose `README.md` records the -deliverables agreed with the human, real inputs, decisions and who took them, write-back keys, and every PR and -issue the session opened. An edit to an earlier task's directory is a finding: a later version names the one it -follows instead. Outputs go through `task_paths(__file__)` to the task's own `results/`, `reports/`, -`figures/`, `outputs/`. Writes to `data//results/` or the central `figures/` are the human lane and are a -finding. +Agent work belongs in a task directory `analysis//.../_vN/`. Check that its README's content is real: +the actual input files, the deliverables agreed with the human, a short summary of each PR. An edit to an earlier +task's directory is a finding: analysis moves forward, and a new version names the one it follows. Writes to +`data//results/` or the central `figures/` are the human lane and are a finding. Every key committed to a shared object carries the task's version suffix **and** appears in that README: an unrecorded key can't be traced back, an unsuffixed one collides with the next version. ### 4. Scientific correctness -The point of the repo. Check that each finding in the deliverables follows from what the code computes: the right -cells, the right grouping, a control where one is needed, and a comparison not confounded by condition, time -point, sample or batch. A number that reaches a deliverable is worth more scrutiny than anything below. +The point of the repo. Check that each finding in the PR body follows from what the code computes: the right cells, +the right grouping, a control where one is needed, and a comparison not confounded by condition, time point, sample +or batch. A number that reaches a deliverable is worth more scrutiny than anything below. ### 5. Reinvention @@ -62,16 +59,17 @@ New code needs a reason to exist. Look outward before accepting it: scverse and repo's sibling code packages, then earlier task directories; a near-match found by grep counts. Name the candidate and what's wrong with it rather than concluding nothing fits. -The acute case is a helper defined twice in one task or copied between tasks: copies drift, and when they compute -a quantity compared *across* tasks, the result is a wrong conclusion. Copying figure code between versions of one -task is fine. +The acute case is a helper defined twice in one task or copied between tasks: copies drift, and when they compute a +quantity compared *across* tasks, the result is a wrong conclusion. Copying code from the version a task follows is +fine. ### 6. Conciseness Prose is reviewed like code. READMEs, docstrings, comments and the PR body: no restating the diff, no filler preamble, no exhaustive caveats. Padding rots the same way dead code does, and these docs are load-bearing for -the next agent. Each fact has one home, the task README: a report or PR body that restates it instead of linking -is a finding, because the copies drift. +the next agent. Each fact is written once: a PR's details in its body, laid out by +`.github/pull_request_template.md`; the task README an overview with a short summary of each PR; findings in the +deliverables. A file that restates another instead of linking to it is a finding, because the copies drift. ## Do not report @@ -79,13 +77,15 @@ is a finding, because the copies drift. - Lock files, and anything under `data/`. - Committed notebook outputs: review changed cells' code, never the output blobs. - Absolute paths built from `main_checkout()`: task outputs are anchored there deliberately. +- A task directory's layout and its README's headings: a hook holds them to the plugin's task template. - Worktree, temp-dir and cwd-relative `data/`/`figures/` path literals in `analysis/` code: a hook blocks them before the file is written. ## Drift older than the diff Parts of a repo may predate these rules. When a PR touches such a file, report the drift once at the lowest -severity and don't block; it gets fixed when a task next touches it. Search the open issues before filing one. +severity and don't block; it gets fixed when a task next touches it. Earlier task directories are not drift: they +stay as they are. Search the open issues before filing one. ## This repo From 3ce67d616e73d68519cefa83439d998f93755f95 Mon Sep 17 00:00:00 2001 From: Marius Lange Date: Thu, 15 Oct 2026 10:47:09 +0200 Subject: [PATCH 4/4] Review guide: a PR body is a dated record; living files don't restate Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_011aQpF4MA9v7dTVK1FqMMVJ --- {{cookiecutter.project_name}}/REVIEW_GUIDE.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/{{cookiecutter.project_name}}/REVIEW_GUIDE.md b/{{cookiecutter.project_name}}/REVIEW_GUIDE.md index 855d4e4..ec2ade7 100644 --- a/{{cookiecutter.project_name}}/REVIEW_GUIDE.md +++ b/{{cookiecutter.project_name}}/REVIEW_GUIDE.md @@ -67,9 +67,10 @@ fine. Prose is reviewed like code. READMEs, docstrings, comments and the PR body: no restating the diff, no filler preamble, no exhaustive caveats. Padding rots the same way dead code does, and these docs are load-bearing for -the next agent. Each fact is written once: a PR's details in its body, laid out by -`.github/pull_request_template.md`; the task README an overview with a short summary of each PR; findings in the -deliverables. A file that restates another instead of linking to it is a finding, because the copies drift. +the next agent. Among the files that keep changing, each fact is written once: findings in the deliverables, the +overview in the task README, which gives each PR a short summary. A PR's body, laid out by +`.github/pull_request_template.md`, is its record as of the merge and may state what the deliverables showed then. A +living file that restates another instead of linking to it is a finding, because the copies drift. ## Do not report