Quality Playbook

Version: 1.6.1 | Author: Andrew Stellman | License: Apache 2.0

Find the bugs that code review misses

Most code review looks at how the code is written. The Quality Playbook looks at what the code is supposed to do, and whether it does it.

The Quality Playbook explores your codebase and works out the behavioral requirements of your code from two sources: the code itself, and your documentation (specs, issues, chat history, post-mortems). Then it runs a three-pass code review and a multi-model spec audit (the Council of Three) against those requirements. The bugs it turns up are the ones that look correct to anyone who doesn't already know the spec:

• a function that silently returns null instead of throwing
• a duplicate-key check that passes when the first value is null
• sanitization that runs after the branch decision it was supposed to guard

It catches bugs that a thorough adversarial code-review prompt misses. The gson bug in the leaderboard below is one: the adversarial review of the same code, made without the playbook, is in that bug's evidence folder and doesn't report it. Along the way it also builds quality infrastructure that your project keeps, and every later review cycle runs against it:

• derived requirements
• functional and integration tests
• contracts and a coverage matrix
• the code-review, spec-audit, and TDD verification protocols themselves

And this isn't theoretical! Maintainers have merged or released fixes for 27 bugs that the Quality Playbook found in Javalin, the Linux kernel, Google's gson, aiohttp, calibre, OpenTelemetry and five other projects.

Quick start

Install into your project's root directory (pick one):

npx quality-playbook install --into . --ai-tool claude     # from npm, no global install
pip install quality-playbook && quality-playbook install --into . --ai-tool claude   # from pip
git clone https://github.com/andrewstellman/quality-playbook   # or clone and ask your AI to install it

Swap claude for cursor, copilot, continue, codex, windsurf, cline, or aider. You need Python 3.10 or later on your PATH.

Run by opening your project in your AI coding tool and telling the agent:

"Run the Quality Playbook on this project."

The agent finds the installed skill on its own and runs the six phases (explore, generate, code review, spec audit, reconcile, verify), pausing after each one until you say "keep going". It writes the results into a quality/ folder. Start with quality/BUGS.md, which lists the bugs it found.

Merged bugs leaderboard

As of 6 November 2026, maintainers have merged or released fixes for these 27 bugs, and 19 more fixes and reports are submitted and waiting. Three of them were private security reports, published by the maintainer as advisories once the fix was released. The full record, including the bugs that were held back, dropped or never filed, is in evidence/README.md.

This is the beginning of the README. Read the rest at the original. Read the full README ↗