From Prototype to Handover: Making Research Software Maintainable

The postdoc who built the analysis tool graduated last summer. The Streamlit app that the consortium relied on for cross-site recruitment monitoring went down in November when the cloud free tier expired. The pipeline that another team uses to score CV evaluations works on the postdoc's laptop and nowhere else, because the dependencies were never written down. The funder will ask, at the next review, what happened to the tools the project committed to.

This is the most common failure mode in academic research software: the prototype works, the developer leaves, the software dies. The fix isn't more discipline applied later. It's a small set of engineering practices applied at the prototype stage — practices that cost almost nothing to add early and cost the project everything when added late or never.

This post is a practical guide to making research software maintainable: what kills it, what saves it, and the minimum-viable handover package that keeps a tool alive past its original developer.

Why research software dies

After working with grant-funded research teams across health, neuroscience, policy, and social-science domains, the same four patterns kill almost every piece of research software.

1. The dependency snapshot was never captured

The tool runs on the developer's laptop with a specific Python version, a specific virtualenv state, a specific R package set. Six months later, on someone else's laptop, half the dependencies have moved. The tool stops importing or starts producing different numbers. Without a frozen dependency manifest (requirements.txt, Pipfile.lock, renv.lock, pyproject.toml), the tool is implicitly tied to one machine.

2. The README was a placeholder

The repo had a README. The README said "Research analysis tool" and listed the three scripts. It didn't say how to install dependencies, how to run the tool, what inputs it takes, or what outputs it produces. The developer who wrote it knew the answers; nobody else does. Documentation isn't a separate task — it's the artefact that makes the tool legible.

3. The deployment was free-tier disposable

The Shiny app deployed to shinyapps.io's free tier. The Streamlit app on Streamlit Cloud's free tier. The static site on Netlify free. Free tiers are good for prototyping; they're not durable infrastructure for grant-deliverable software. When billing changes, when usage limits are hit, when the platform pivots, free-tier tools quietly disappear.

4. The maintenance plan was implicit

The plan, such as it was, was "the postdoc will keep an eye on it". When the postdoc leaves, the plan ends. There's nobody named in writing as responsible for the next 24 months. The institution doesn't know the tool exists at the level needed to assign it. Research workflow software without a written maintenance handoff is software waiting to die.

Each of these is small in the moment and devastating in aggregate. None requires sophisticated engineering to fix.

What saves research software

Five practices, applied during the prototype phase, change the survival rate dramatically.

Practice 1: Pin dependencies at the start, not the end

The first commit of the prototype should include a frozen dependency manifest. pip freeze > requirements.txt for Python; renv::snapshot() for R; lockfiles checked in for whatever language ecosystem the project uses. This is a 30-second cost on day one and a project-saving asset on day 365.

Practice 2: Write the README as a fresh-laptop test

The README should answer four questions in order:

1. What is this? — one paragraph
2. How do I install it? — exact commands, copy-pasteable
3. How do I run it? — exact commands, with a sample input
4. What does it produce? — file structure of outputs, one example

Test the README by running through it on a different machine, or by asking a colleague who hasn't seen the tool. If they can't get it running in 15 minutes, the README is incomplete.

Practice 3: Choose a stack the institution can support

The right stack for research software isn't the most fashionable one. It's the one your institution can hire for, or that your institutional RSE team already supports.

For research projects in 2026, the durable choices are:

• Python + standard scientific stack (pandas, numpy, scipy, matplotlib) for analysis
• R + tidyverse for statistical work where R is the lingua franca
• Node.js / TypeScript + a mainstream web framework (Next.js, FastAPI for the backend) for tools
• Postgres for any persistent data layer
• Containerised deployments (Docker) for anything that needs to run on a server

Avoid: niche frameworks that depend on a single maintainer, languages your institution has nobody hireable in, platforms with fragile free tiers.

Practice 4: Deploy to durable infrastructure from the start

Don't prototype on free tiers. Use:

• Your institution's research-software-engineer (RSE) hosting if available
• A managed container service with a stable pricing model (Fly.io, Render, Railway, AWS App Runner) — €10–20/month for a low-traffic research tool
• Your institution's Kubernetes cluster if it has one and your project warrants it

The cost difference between free and durable is typically under €300 per year. The reliability difference is the difference between "tool is alive" and "tool is dead".

Practice 5: Write the handover before the developer leaves

The handover document is not "everything I know about this tool". It's "the minimum someone else needs to keep this tool running". Specifically:

• A runbook for common operational tasks (deploy, restart, update dependencies, investigate failures)
• An incident playbook for known failure modes (auth breaks, cloud bill, dataset format changes)
• A list of all credentials, accounts, and infrastructure dependencies, with where they're stored
• A named successor — a specific person, with manager sign-off, who is responsible for the next 24 months
• A retirement plan if no successor is available — when does the tool come down, and what replaces it

This is uncomfortable to write because it acknowledges that the tool will outlive the original developer's involvement. That acknowledgement is the precondition for survival.

The minimum-viable handover package

When a research tool transitions from "developer-active" to "team-maintained" — typically when the original developer graduates, rotates off, or moves institutions — the deliverables your team needs are:

| Item | What's in it | |---|---| | Repository with current code | Full source, in a long-term home (institutional GitLab, GitHub Enterprise, Zenodo for archival) | | Frozen dependency manifest | requirements.txt / lockfile committed and versioned | | README that passes the fresh-laptop test | Install, run, expected output — verified on another machine | | Runbook | Operational procedures: deploy, update, restart, recover | | Incident playbook | Known failure modes + recovery procedures | | Credentials handoff | Account access, where credentials are stored, who can rotate them | | Maintenance contract | Named successor, period of responsibility, escalation path | | Retirement clause | Conditions under which the tool is decommissioned |

Eight items. None are technically hard. All are routinely missing.

The 30-minute fresh-laptop test

The single highest-leverage diagnostic for any research tool: pick someone who didn't build it, give them a fresh laptop, hand them the README, and watch them try to run the tool. Block 30 minutes.

Score:

• They got it running in 15 minutes: A grade — the tool is in good shape
• They got it running with one or two minor blockers: B grade — fix those, you're close
• They got it running in 30 minutes after several blockers: C grade — README needs work
• They didn't get it running: F grade — the tool will not survive the original developer

Most research tools are C or F when honestly tested. Most teams have never run the test, which is why they're surprised when the tool dies.

When to bring in external help

A research-software handover engagement is the right move when:

• The original developer is leaving in less than 3 months and no successor is in place
• The tool is operationally important (active users, ongoing data flow) but undocumented
• The funder expects the tool to remain accessible for a stated period after grant end
• The team is not staffed to absorb the maintenance themselves and needs a structured handoff to either an internal team or to the institutional RSE group

Pragma's Research Tool MVP engagement covers the build phase; we also do takeover engagements where the goal is hardening an existing prototype into something maintainable. The output is the 8-item handover package above plus the engineering work needed to make each item real (dependency pinning, deployment migration, README rewrite, runbook drafting).

If you have a prototype that's working but not maintainable, that's the engagement.

Three things to do this week

1. Pick one prototype tool from your project. Run the 30-minute fresh-laptop test. Be honest about the grade.
2. Whatever the grade, identify the lowest-cost fix that moves it up one letter. Often it's writing 2 paragraphs of README.
3. If the grade is C or F and the tool is operationally important, request a scope review. We'll define the minimum-viable handover package and what it costs to ship.

Research software doesn't have to die. Most of the engineering practices that prevent its death are not sophisticated. The discipline is doing them at the start, when they cost almost nothing — instead of at the end, when they cost the project.