mri-research-workflow · diff

v0.8.0 to v0.12.0

59 added, 120 removed. Audit A to A.

---

name: mri-research-workflow

description: >-

- End-to-end MRI research assistant — take a project from idea to a published

- paper, and help write it. Use this WHENEVER the user wants to plan or run an

- MRI (or MRI + machine-learning) study and publish it: literature survey and

- finding the gap, forming a hypothesis/claim, designing experiments (datasets,

- baselines, metrics, ablations), running them, analyzing results, making

- figures/tables, and drafting + submitting a manuscript to a venue such as

- MICCAI, Magnetic Resonance in Medicine (MRM), JMRI, IEEE TMI, CVPR or NeurIPS.

- It connects the workflow with specialized MRI skills. Triggers:

- "help me write a paper", "run experiments and publish", "submit to CVPR / MRM /

- MICCAI", research plan, related work, ablation study, rebuttal, camera-ready,

- reproducibility, paper draft, abstract.

+ Read before designing, analysing, writing up or reviewing an MRI study:

+ results sections with a claim ledger, referee reports, gaps and proposals

+ from a supplied corpus, sample size and repeatability (ICC with CI) from

+ pilot data, group comparisons, cutoffs and held-out splits. Use it, not the

+ method skills, for manuscripts. Prevents overclaiming, numbers that do not

+ match the data, non-verbatim quotes, wrong statistical units and over-limit

+ texts. Ships a writing checker, study statistics and the finish check every

+ MRFoundry skill runs.

metadata:

author: Ke Wang

- version: "0.8.0"

+ version: "0.12.0"

---

- # MRFoundry: MRI Research Workflow (idea → paper)

- You are a research-project shepherd and writing partner. Take the project through

- the stages below, doing the work with the user, and hand off domain steps to the

- relevant skills. **Pick the target venue early** — it shapes framing, rigor, and

- format.

- ## Papers and textbooks

- See the [annotated reading list](references/reading-list.md) for primary papers,

- textbooks, publication details, direct source links and what each source supports.

- Use the [repo-wide reference index](https://github.com/KeWang0622/MRFoundry/blob/main/REFERENCES.md) to navigate across skills.

- When using a method, cite its specific source; distinguish paper evidence from

- software instructions and current venue/safety requirements.

- ## Evaluation and original-source credit

- Before comparing methods or making scientific claims, identify the intended task

- and the evidence needed to support it. Use the [evaluation and attribution guide](https://github.com/KeWang0622/MRFoundry/blob/main/skills/mri-research/references/evaluation-and-attribution.md)

- for evaluation planning, failure tests and auditing citations in the actual output.

- Report benchmark metrics when relevant; do not infer universal superiority or

- clinical validity from them. Cite original methods and software separately, and

- flag claims whose source or support could not be verified.

- If the shared guide is absent in a standalone install, retrieve

- `skills/mri-research/references/evaluation-and-attribution.md` from the

- [official repository](https://github.com/KeWang0622/MRFoundry).

- ## Project research memory

- If only the legacy `.mri-research/` notebook exists, migrate it with the project

- memory initializer before creating new notes; preserve existing evidence.

- For project experiments, read `.mrfoundry/INDEX.md` when present and retrieve

- only relevant preferences, environment notes and evidence-linked lessons. After

- meaningful runs or corrections, record outcomes, failures, limitations and next

- steps; revise scoped lessons without erasing history. Keep user preferences

- separate from scientific findings. Use the [project memory workflow](https://github.com/KeWang0622/MRFoundry/blob/main/skills/mri-research/references/project-memory.md)

- to initialize the folder or connect project `CLAUDE.md` / `AGENTS.md`. If the hub

- is absent, retrieve the reference from the official skill repository.

+ # MRFoundry: MRI Research Workflow (studies, statistics, write-ups, reviews, deliverables)

- ## Tool setup before execution

+ ## Route

- For any application this skill uses, check for a compatible installation and

- follow the official upstream's setup instructions. Within the authorized task,

- install missing dependencies yourself in an isolated environment, run a small

- upstream example, then execute the user's workflow. Do not leave routine setup

- to the user or replace a missing tool with a homemade numerical implementation.

- Use established simulators/solvers; write only necessary configuration and glue.

- If blocked, report the actual obstacle and an established alternative.

- Read the [tool setup guide](https://github.com/KeWang0622/MRFoundry/blob/main/skills/mri-research/references/tool-setup.md) when installing,

- repairing, or choosing an execution environment. If the hub is not installed,

- retrieve that reference from the official `KeWang0622/MRFoundry` repository.

+ | Task | Read | Check before finishing |

+ |---|---|---|

+ | Results section, abstract, claim ledger | [write-results](references/write-results.md) | `scripts/write_check.py --claims ...` |

+ | Methods/statistics review of a manuscript | [write-review](references/write-review.md) | `scripts/write_check.py --quotes ...` |

+ | Research gap and proposal from a supplied corpus | [write-proposal](references/write-proposal.md) | `scripts/write_check.py --ids ... --schema ...` |

+ | Repeatability and sample size from pilot data | [plan-sample-size](references/plan-sample-size.md) | `scripts/write_check.py --schema ... --numbers-in ...` |

+ | Group statistics, repeatability, cutoffs | `scripts/study_stats.py` (table below) | finish check |

+ | Study or method-comparison design: baselines, endpoints, ablations, failure tests | [evaluation guide](../mri-research/references/evaluation-and-attribution.md) | |

+ | Paper planning, venues, reviewer responses | [paper-writing guide](references/paper-writing.md) | |

+ | Literature summary or related work | [literature access](../mri-research/references/literature-access.md): state topic and date window, verify primary records, merge versions, label abstract-only items, keep reported claims apart from your assessment | |

+ | Deliverables with code | | finish check (below) |

- ## The flow

+ `python .agents/skills/mri-research-workflow/scripts/write_check.py --help` lists every flag; each FAIL line

+ says what to fix. Fix the files, never the checker, and run it again.

- 1. **Frame.** Survey related work (use the `literature-access` reference — arXiv,

- Semantic Scholar, OpenAlex, PubMed, or a paper-search MCP). State the gap and a

- single crisp claim/hypothesis. Choose the venue using the writing guide below.

- 2. **Design.** Pick datasets (mind DUAs — see the hub's `data-and-formats`),

- baselines, the proposed method, task-specific endpoints and ablations up front. Use the

- evaluation guide to specify reference standards, failure tests and what would

- falsify the claim. Plan compute, reproducibility and the scope of independent

- validation; keep tuning and test data separate. Record seeds, configurations

- and run logs.

- 3. **Run.** Hand off to the experts:

- - reconstruction experiments → **mri-reconstruction** (runs BART/SigPy).

- - training / DL recon → **deep-learning-recon**.

- - diffusion analysis → **diffusion-mri**; acquisition/sequences →

- **pulse-sequence-design**; hardware → **mri-hardware**.

- Track every run (config, seed, data split, metric).

- 4. **Analyze.** Evaluate the planned endpoints, uncertainty, relevant subgroups

- and failure cases; show matched images and difference maps when informative.

- Explain what image metrics and reader assessments do and do not establish.

- Separate benchmark reproduction from independent implementation or external

- validation, and limit conclusions to the evidence actually collected.

- 5. **Write.** Use the paper-writing guide below; draft from verified evidence in the

- venue-provided format (LaTeX or Word as appropriate).

- 6. **Submit & revise.** Follow venue mechanics (blind review, rebuttal,

- camera-ready, or journal revision cycles). Prepare releases/preprints when

- requested; submission or publication requires user authorization.

+ ## Rules for every write-up, review and plan

- ## Choose the venue and summarize related work

+ 1. **Definitions are literal.** Apply each definition the task gives to every record or entry IN CODE (one row

+ per record with the fields the definition uses and the decision). Add no criteria and drop none.

+ 2. **Schemas are exact**: key names, vocabulary spellings, one value versus a list, integers. An endpoint

+ `unit` is the measurement unit (ms, 1/s, mm²/s, %), never the unit of analysis.

+ 3. **Numbers come from files**: compute in code, keep one ledger, write prose from it with the same rounding;

+ no new statistics unless asked. Units and precision as the task states.

+ 4. **Claims match the evidence**: a CI including 0 is reported as no difference detected; exploratory results

+ are labelled as such in every clause; no causal or clinical claim beyond the design.

+ 5. **Citations are closed**: only supplied keys or record IDs; a record supports a statement only if it states

+ that fact itself.

+ 6. **Limits**: word limits count every token; stay below 90 %. Quotes are one contiguous verbatim passage.

- Use the [venue and literature-digest guide](https://github.com/KeWang0622/MRFoundry/blob/main/skills/mri-research/references/publishing.md)

- for MRM, JMRI, TMI, MedIA, MICCAI, ISMRM, CVPR and related venues. Distinguish

- journal articles, conference papers, meeting abstracts and preprints. Match the

- scientific contribution to the audience; recheck the target year/track's official

- instructions before selecting a template, limits or submission schedule.

+ ## Study statistics (`scripts/study_stats.py`, tested; `--api` lists signatures)

- For a journal/conference summary, state the topic and date window; verify primary

- records; deduplicate versions; compare methods, data, findings and limitations.

- Label abstract-only summaries and separate reported claims from your assessment.

- Give a synthesis and useful next experiments, not just a list of titles.

+ | Need | Function |

+ |---|---|

+ | Two groups | `two_sample_t` (pooled or Welch t, CI, p, pooled SD, Hedges g), `auc`, `subject_bootstrap` |

+ | Paired | `paired_difference` (t CI, Cohen's dz), `bland_altman` |

+ | Repeatability | `repeatability` (wSD with chi-square CI, wCV, RC), `icc`, `icc_ci` (F-based CI, all six forms) |

+ | Sample size | `n_per_group`, `n_paired` (normal or exact t), `sd_of_differences`, `n_enrol`, `combined_fraction`, `n_total_unbalanced` |

+ | Cutoffs | `threshold_on_dev`, `balanced_accuracy` |

- ## Writing and revising for MICCAI, MRM, JMRI and TMI

+ The statistical unit is the subject (or the unit the plan names), never the voxel; fix every setting, threshold

+ and cutoff on development subjects and apply it unchanged to held-out subjects; the study's analysis plan

+ overrides these defaults.

- Read the [paper-writing guide](references/paper-writing.md) for venue-specific

- framing, evidence requirements, figure planning and revisions. Start with the

- [paper plan](assets/paper-plan.md) and use the

- [reviewer-response template](assets/reviewer-response.md) when revising.

- These are planning aids; retrieve the official manuscript template separately.

- Keep planned experiments distinct from actual results. Link every numerical

- claim to its analysis, and make unsupported text an explicit placeholder.

+ ## Finish check (every task with files to deliver)

- ## Resources & handoffs

+ python .agents/skills/mri-research-workflow/scripts/finish_check.py \

+ --require <every deliverable name the task lists> \

+ --rerun "python <entrypoint> <documented arguments with {inputs} and {out}>" --inputs <input folder> \

+ [--expect <files the entrypoint must write>] [--json report.json:key1,key2/sub] [--range FILE:LOW:HIGH]

- - Manuscript logistics (journals, LaTeX classes, reporting standards, abstracts):

- hub `publishing` —

- https://github.com/KeWang0622/MRFoundry/blob/main/skills/mri-research/references/publishing.md

- - Finding/monitoring literature: hub `literature-access` —

- https://github.com/KeWang0622/MRFoundry/blob/main/skills/mri-research/references/literature-access.md

- - Preprints: arXiv (eess.IV / physics.med-ph / cs.CV). Reviews on OpenReview for

- some venues.

+ It fails on missing or misnamed deliverables, an entrypoint stored apart from its outputs, no environment

+ record when code is delivered, an entrypoint that fails in a fresh folder, and map medians outside the

+ expected range. Without code, use `--require` only. `--help` lists the flags of either checker: run them, do not

+ read their sources. A standalone single-file entrypoint takes tested helpers with

+ `python .agents/skills/mri-research-workflow/scripts/inline_helpers.py <module.py> <functions> --into <entrypoint.py>`.

- ## What you can produce

+ Citations: [reading list](references/reading-list.md).

+ Project notes (only with `.mrfoundry/INDEX.md`): [project memory](../mri-research/references/project-memory.md).

- A research plan, an experiment-tracking scaffold, drafted sections (intro,

- related work, method, results narrative), ablation/table templates, a rebuttal

- draft, and a submission/reproducibility checklist. Always keep claims matched to

- evidence, and defer clinical interpretation to a qualified reader.