--- title: rewrites.bio description: Principles for AI-assisted rewrites of bioinformatics tools url: https://rewrites.bio source: https://github.com/seqeralabs/rewrites.bio updated: 2026-06-16 --- # rewrites.bio > Principles for rewriting bioinformatics tools with AI AI coding assistants have made it possible to rewrite established scientific software in days rather than years. A wave of rewrites is coming to bioinformatics. These principles are a suggestion for how we can handle them responsibly. ## 1. Introduction ### 1.1 The opportunity Bioinformatics datasets have grown faster than the tools that process them. The cost shows up in compute bills, carbon footprint, and time to results. - **Scale:** A pipeline like nf-core/rnaseq runs on millions of samples per year. Ten wasted minutes per sample is decades of compute, annually. - **Environment:** Wasted CPU-hours mean kilowatt-hours and CO2. Rewrites running 10-50× faster can save hundreds of tonnes of emissions. - **Science:** Hours waiting for results are hours not spent testing hypotheses or exploring new directions. AI coding assistants now let a domain expert produce a working reimplementation in days rather than years. Fast code is now cheap. Scientific insight, validation, and trust are not. ### 1.2 The risk Cheap code is not the same as correct code. AI-generated implementations are fluent and fast, but confidently wrong in ways that are easy to miss. - **Correctness:** A rewrite that silently produces different results poisons every analysis built on it. - **Attribution:** Ignoring the original authors' contributions damages the incentive structures that made the tool possible. - **Fragmentation:** Competing rewrites with different behaviour leave users unsure which to trust. Abandoned projects block better alternatives. The existing tools are correct, and that correctness is hard-won. Rewrites inherit a responsibility: to match outputs exactly, to credit the work they stand on, and to be honest about what they have and have not validated. > *A wave of AI-assisted rewrites is coming. The question is not whether it will happen, but whether it will happen well.* ## 2. Philosophy Before writing any code, three commitments shape everything else. ### 2.1 Credit the original authors Behind every bioinformatics tool is years of work: algorithm design, edge-case hunting, user feedback, and maintenance. A rewrite stands entirely on that foundation. Without the original, a rewrite cannot even be validated. Make credit visible: - **README** and documentation - **Papers** and preprints - **Downstream reports** using the rewrite's results - **Credits page** with citations, DOIs, author lists, and versions When users cite your rewrite, they should know to cite the original too. This is how science tracks provenance. Obscuring lineage undermines the incentives that produced the original work. ### 2.2 Emulate exactly The goal is a faster tool that produces the same results. A rewrite that changes outputs, even as "improvements", is a different tool. It cannot inherit the original's validation or be substituted without re-validation. Emulate exactly means: - **Deterministic tools:** byte-for-byte identical output files - **Floating-point tools:** results within acceptable numerical precision (defined by scientists, not convenience) - **Everything counts:** header formats, column ordering, file naming, summary statistics ### 2.3 Be transparent about AI When an AI writes the implementation, say so. Correctness is determined by output comparison, not by who wrote the code - but users should know how it was built. Document clearly in the README and any paper: - **AI tools:** which were used and what role they played - **Verification:** how correctness was validated (e.g., "against mytool v1.0 on real sequencing data") - **Gaps:** where validation coverage is thin or incomplete Output comparison catches what you tested, not what you haven't. Commit to ongoing validation as new use cases emerge. ## 3. Planning The decisions made before you write the first function determine most of the outcome. Scope, validation strategy, and architecture all matter more than the choice of language. ### 3.1 Think big The biggest performance wins come from rethinking architecture, not just porting code. Modern pipelines chain discrete tools, each doing I/O. A straight port to a faster language captures only a fraction of what is available. Questions to ask: - **Upstream:** what preprocessing does this tool assume? Can that be folded in? - **Downstream:** what immediately consumes the output? Can that be folded in too? - **Intermediate files:** can steps share data in memory instead of writing gigabytes of temporary BAM files? - **Hardware:** consider other architectures likw `#aarch64` to balance performance and sustainability. Accelerators (GPU/TPU) can help too, but only with robust validation. This doesn't mean building an unvalidatable monolith. But consider what a pipeline designed from scratch would look like, knowing where the bottlenecks are. ### 3.2 Work small Thinking big about architecture does not mean building big in one go. The implementation strategy should be the opposite: small, tight iteration loops, each step validated against the original before moving on. Why this matters: - **Localised debugging:** when something is wrong, you already know where to look - **Continuous validation:** AI agents are unreliable for correctness - validate every step - **Productive iteration:** "output doesn't match on paired-end data" is actionable; "implement the whole pipeline" is not Start with the simplest function that produces testable output. Validate it. Then extend. ## 4. Building The building phase is where principles meet reality: data that behaves unexpectedly, performance that doesn't match theory, and users who need the tool to work before they trust it. ### 4.1 Test and benchmark with real data Synthetic data is useful for quick iteration but insufficient for validation. Real sequencing data has error patterns and quality profiles that generators don't replicate. Test comprehensively: - **Diversity:** multiple organisms, platforms, and library preps - **Edge cases:** empty files, single-read files, very large files - **Benchmarks:** document hardware, dataset, exact commands, and output comparison Speed claims need evidence. Document your hardware, dataset, and exact commands so anyone can reproduce the comparison. If performance varies across data types, show that too. ### 4.2 Build only what you need Feature completeness is not the goal - output correctness on the features that matter is. Most tools have accumulated flags and edge cases over years; not all are used in your target pipeline. A focused approach: - **Audit usage:** identify exactly which capabilities your pipeline uses - **Fail loudly:** for unsupported features, error with a clear message pointing to the original - **Never ignore:** silently dropping flags or producing wrong output breaks trust A rewrite that does four things correctly is more valuable than one that claims fifteen and does twelve right. Scope can expand as the project matures; it cannot easily contract once users depend on it. ### 4.3 Pin versions and document Every equivalence claim is implicitly about a specific version. *"Compatible with mytool"* is meaningless. *"Bit-identical output to mytool v1.0, validated on the dataset in benchmarks/"* is testable. Document in the repository (not a blog post): - **Versions:** exact version of every original tool validated against - **Commands:** exact command lines used for comparison - **Data:** datasets, methodology, and date - **Policy:** how you handle upstream version updates When the original releases a new version, you need a process: major bumps often change formats, patches may fix bugs affecting your outputs. Communicate your policy to users. ## 5. Stewardship A rewrite is not a one-time act. Once other researchers build pipelines on your tool, you owe them continued correctness as upstream tools evolve, transparent governance, and responsible engagement with the original projects. ### 5.1 Maintain and govern Someone needs to be responsible for what comes next, and that should be visible before you release. Plan for the long term: - **Triage issues** as users find edge cases your test suite missed - **Re-validate** when the original tool releases updates - **Expand benchmarks** as new data types and edge cases surface - **Review PRs** and grow a contributor community Put governance in place before release: CONTRIBUTING.md, CHANGELOG.md, versioned tags, changelogs, and a commitment to acknowledge issues. ### 5.2 Preserve compatibility The strongest argument for adopting a rewrite is zero migration cost. Identical outputs mean swapping into an existing pipeline is a one-line config change. What identical means: - **File names:** same output naming conventions - **Formats:** same column headers, same ordering, same summary statistics - **Parsing:** every MultiQC module and downstream script works unchanged This reversibility makes adoption risk-free. Researchers running production pipelines cannot re-validate their entire analysis history every time they update a tool - but they will try a rewrite they can test on one run, confirm matches, and roll back if needed. ### 5.3 Release as open source The tools you are rewriting were built by the open-source community, validated against publicly funded data, and distributed freely. A rewrite that closes the source extracts value without contributing back. Open source matters for adoption: - **Transparency:** researchers need to inspect code to understand what it does to their data - **Accessibility:** HPC clusters often don't have commercial software available - **Continuity:** users can fork if the project is abandoned Check licenses before you start. Permissive licenses (MIT, Apache-2.0, BSD) let you release under any license; copyleft (GPL) requires compatible licensing. Whether a reimplementation is a "derived work" depends on jurisdiction - err on the side of caution. License archaeology is far easier before you ship than after. ### 5.4 Contribute upstream responsibly Building a rewrite puts you in an unusual position: you've studied the original closely and found its edge cases. A reproducible bug report is a real contribution to science. But be careful - AI agents are confidently wrong in subtle ways. Before filing upstream: - **Verify manually** with the original tool on clean, well-understood data - **Rule out** your reimplementation, malformed input, or a misread spec - **Never use** AI-generated test cases as evidence Do not automate bug reports. Open-source maintainers are usually volunteers - a firehose of issues burns out people whose work benefits everyone. The bar for filing: you fully understand the problem yourself, you can create a minimal reproducible example using the upstream tool that demonstrates it, and you've considered whether you can also contribute a fix. --- *These principles are a starting point, not a checklist.* Every rewrite will weigh these principles differently. We hope that they can be a guide to help you shape the questions you ask along the way. Discuss and contribute at [github.com/seqeralabs/rewrites.bio](https://github.com/seqeralabs/rewrites.bio) --- Website: [rewrites.bio](https://rewrites.bio) Source: [github.com/seqeralabs/rewrites.bio](https://github.com/seqeralabs/rewrites.bio)