Project Health

Managing Research Software Projects

Greg Wilson

2026

Learning Objectives

  • Name the six dimensions of a minimum viable research software project.
  • Score your own project on each dimension.
  • Identify the highest-priority gaps.

What “Healthy” Means

  • Healthy means findable, reproducible, and maintainable by someone other than you.
  • Most research projects score poorly on these until someone complains.
  • Use six dimensions to assess the state of your project.

1. Findability

  • Has a DOI
  • Has a CITATION.cff file
  • Is listed in package registries

2. Reproducibility

  • A setup specification (e.g., pyproject.toml or requirements.txt)
  • A Makefile or similar to re-run standard analyses

3. Testability

  • Has tests
  • With coverage
  • That are run before commits locally
  • And on the forge

4. Contribution

  • A CONTRIBUTING.md file
  • That a stranger can follow
  • On their machine

5. Governance

  • Written rules for who decides what
  • That explain how people without a vote can raise concerns

6. Sustainability

  • More than one person can release
  • A documented handover plan

Dependencies Between Dimensions

  • The six dimensions are not independent.
  • Low governance almost always means poor sustainability.
  • Poor reproducibility usually means low testability.
  • Tests that pass on one machine may fail elsewhere.
  • The dimensions focus on software first, and on the team later.

Honesty Is Uncomfortable

  • An honest audit tells you which gap to fix first.
  • Improving your lowest dimension by one point matters more than polishing a 4/5 dimension.
  • LLMs usually give your project a higher score than it deserves.
    • LLMs cannot know whether your CONTRIBUTING.md is tested or CI actually blocks merges.

What about AI?

  • LLM tools can flag semantic bugs and security issues in a first pass
  • LLMs can summarize what a PR actually changes versus what it claims it changes
  • LLM commit messages are often fluent but inaccurate

Dependencies (5 min)

Sort the six dimensions in the order in which you think they should be tackled. Compare your order to other people’s. Are any of the differences important?

Project Audit (15 min)

Using the six-dimension rubric, score your project. Include evidence for each dimension, (e.g., the URL of the governance description). Repeat the audit using an LLM. Where does the LLM assume something exists that doesn’t? Where do the LLM’s scores differ from yours?

Action Planning (5 min)

  1. Identify the two dimensions with the largest gaps.

  2. Write one concrete action you could take in the next two weeks to raise the score.