Attribution: Sourced from andrewstellman/quality-playbook by Andrew Stellman, licensed Apache-2.0 (see LICENSE.txt); the author also contributed it to github/awesome-copilot. Modified for this collection: the phase sections, artifact contract, run-state rules, and runner notes were moved unchanged from this file into references/, and the phase prompts now point there.

Quality Playbook Generator

Plan Overview — read this first, then explain it to the user

Before reading any other section of this skill, understand the plan and its dependencies. Each phase produces artifacts that the next phase depends on. Skipping or rushing a phase means every downstream phase works from incomplete information.

Phase 0 (Prior Run Analysis): If previous quality runs exist, load their findings as seed data. This is automatic and only applies to re-runs.

Phase 1 (Explore): Run the v1.5.3 documentation intake first (python -m bin.reference_docs_ingest <target> to walk reference_docs/ — cite/ files produce quality/formal_docs_manifest.json records; top-level files are loaded as Tier 4 context via reference_docs_ingest.load_tier4_context(<target>)). Then explore the codebase in three stages: open exploration driven by domain knowledge, domain-knowledge risk analysis, and selected structured exploration patterns. Write all findings to quality/EXPLORATION.md. This file is the foundation — Phase 2 reads it as its primary input.

Phase 2 (Generate): Read EXPLORATION.md and produce the quality artifacts: requirements, constitution, functional tests, code review protocol, integration tests, spec audit protocol, TDD protocol. (AGENTS.md at the target's repo root is generated by the orchestrator AFTER Phase 6, not by you in Phase 2 — see "File 6" below for the contract.)

Phase 3 (Code Review): Run the three-pass code review against HEAD. Write regression tests for every confirmed bug. Generate patches.

Phase 4 (Spec Audit): Three independent AI auditors review the code against requirements. Triage with verification probes. After triage, the same Council runs the v1.5.3 Layer-2 semantic citation check — one prompt per reviewer, structured per-REQ verdicts for every Tier 1/2 citation, output to quality/citation_semantic_check.json. Write regression tests for net-new findings.

Phase 5 (Reconciliation): Close the loop — every bug from code review and spec audit is tracked, regression-tested or explicitly exempted. Run TDD red-green cycle. Finalize the completeness report.

Phase 6 (Verify): Run self-check benchmarks against all generated artifacts. Check for internal consistency, version stamp correctness, and convergence.

Phase 7 (Present, Explore, Improve): Present results to the user with a scannable summary table, offer drill-down on any artifact, and provide a menu of improvement paths (iteration strategies, requirement refinement, integration test tuning). This is the interactive phase where the user takes ownership of the quality system.

Every bug found traces back to a requirement, and every requirement traces back to an exploration finding.

The critical dependency chain: Exploration findings → EXPLORATION.md → Requirements → Code review + Spec audit → Bug discovery. A shallow exploration produces abstract requirements. Abstract requirements miss bugs. The exploration phase is where bugs are won or lost.

MANDATORY FIRST ACTION: After reading and understanding the plan above, print the following message to the user, then explain the plan in your own words — what you'll do, what each phase produces, and why the exploration phase matters most. Emphasize that exploration starts with open-ended domain-driven investigation, followed by domain-knowledge risk analysis that reasons about what goes wrong in systems like this, then supplemented by selected structured patterns. Do not copy the plan verbatim; paraphrase it to demonstrate understanding.

Quality Playbook v1.5.6 — by Andrew Stellman https://github.com/andrewstellman/quality-playbook

Generate a complete quality system tailored to a specific codebase. Unlike test stub generators that work mechanically from source code, this skill explores the project first — understanding its domain, architecture, specifications, and failure history — then produces a quality playbook grounded in what it finds.

How to run this — v1.5.4 self-encoded invocation contract

If the operator hands you this skill (or points you at any QPB-installed target) and says "Run the Quality Playbook" — possibly with a hint like "this is a bootstrap run" or "run on itself" or "self-audit" — this section tells you exactly what to do. The operator should not need to provide additional instructions; the canonical invocation, the defaults, the guardrails, and the output contract all live here.

Pick your execution mode

QPB ships in two execution shapes. Pick the one that matches your runtime — the wrong choice produces the codex-on-codex indirection pathology surfaced by the 2026-04-30 bootstrap test.

Mode	When this is you	What you do
A. Skill-direct (UI-context)	You are a coding agent (Claude Code, Cursor, Copilot, Codex desktop, etc.) handed this skill in your own chat. Your runtime IS the reasoning loop — you read files, you write files, you decide.	Walk through Phase 1 → Phase 6 yourself using the externalized phase prompts in phase_prompts/. Write artifacts into the target's quality/ directory directly. No subprocess, no runner.
B. Runner-driven (CLI-automation)	The operator is invoking python3 -m bin.run_playbook deliberately — to batch across multiple targets, drive a headless CI run, or fan out per-phase work to a different model than the one reading this prose.	The orchestrator spawns a CLI agent (claude, copilot, codex, or cursor) per phase. You (or whoever is reading this) are the operator-side control loop, not the per-phase reasoner.

Both modes use the same phase prompt content — the phase_prompts/*.md files at the repo root are the single source of truth, loaded by bin/run_playbook.py::_load_phase_prompt and read directly by Mode A walkthroughs. The only thing the two modes differ on is WHO drives — you (Mode A) or the orchestrator subprocess-spawning a CLI agent (Mode B).

When in doubt, default to Mode A. If the operator wanted runner-driven invocation they would have run the runner themselves; if they pasted "Run the Quality Playbook" into your chat, they want you to drive. The Mode B section below tells you what to do if the operator explicitly invokes the runner.

Mode A — skill-direct walkthrough (UI-context)

The operator's prompt is just "Run the Quality Playbook" (or "run on itself", "self-audit", etc.). You drive every phase inline.

For each phase 1..6, in order:

1. Load the phase prompt. Read phase_prompts/phaseN.md (resolve via the same install-location fallback list documented for references/ below). For phase1.md, substitute {seed_instruction} (the prelude that says "skip Phase 0/0b" — empty string when seeds are allowed) and {role_taxonomy} (the taxonomy block rendered from the role taxonomy below). For phase2.md through phase6.md, the file is pure-literal — read it verbatim.
2. Execute the phase per the prompt. Read the inputs the prompt names, do the analysis, write outputs into the target's quality/ directory.
3. STOP at the end-of-phase boundary. Every phase prompt ends with an "IMPORTANT: Do NOT proceed to Phase N+1" instruction. Honor it. The operator advances to the next phase by saying so.

You are responsible — without the orchestrator's structural backstop — for the same source-unchanged invariant the runner enforces: do NOT modify any file outside the target's quality/ directory. In Mode B the gate would catch this; in Mode A you are the gate. The 2026-04-30 bootstrap test specifically failed on a Phase 2 LLM modifying the target's root AGENTS.md — the same failure mode applies in Mode A.

For the bootstrap-run (self-audit) variant of Mode A, see "Bootstrap mode" below — the only delta is that the target IS the QPB repo, so cite the same phase_prompts/ files you read from.

Mode A scope — what's covered, what's Mode-B-only

Council 2026-04-30 P1-3: the per-phase walkthrough above scopes Mode A to phases 1..6. The following surfaces are deliberately Mode-B-only — if the operator wants them, point them at the runner instead of trying to drive them yourself:

• Phase 0 / Phase 0b (seed injection from prior runs). The orchestrator handles seed discovery, prior-run scanning, and seed-prompt injection. In Mode A, treat every run as --no-seeds (skip Phase 0/0b entirely, start at Phase 1). If the operator explicitly asks for seed-driven exploration, hand off to Mode B (python3 -m bin.run_playbook --with-seeds <target>).
• Phase 7 (interactive Present / Explore / Improve). This phase is a back-and-forth dialogue with the operator about the generated artifacts; it has no pre-baked prompt in phase_prompts/. After Phase 6 in Mode A, present the artifact summary table inline (see "What this run produces" below for the file list) and let the operator drive what to explore next conversationally — that IS Phase 7. There is no orchestrator subprocess to spawn.
• Iteration strategies (gap / unfiltered / parity / adversarial). Iterations re-enter the playbook with a strategy-specific addendum. In Mode A, after Phase 6 completes cleanly, hand off to Mode B for iterations: python3 -m bin.run_playbook --next-iteration --strategy <name> <target>. The iteration prompts (phase_prompts/iteration.md) ARE single-source-of-truth, but the iteration-orchestration loop (rotating through gap → unfiltered → parity → adversarial) is the runner's job. A Mode A operator who wants iterations after Phase 6 should be told: "Phase 6 is done; run python3 -m bin.run_playbook --full-run <target> to get all four iteration strategies, or pick one strategy explicitly with --next-iteration --strategy gap."

If the operator asks for one of these surfaces in Mode A and the request is ambiguous (e.g., "also do the iterations"), surface the mode-handoff explicitly rather than improvising — improvisation is how the prompt content drifts away from the runner's canonical loop.

Mode B — runner-driven invocation (CLI-automation)

The operator runs python3 -m bin.run_playbook <target> themselves, and the orchestrator spawns a CLI agent per phase. Read references/runner_mode.md only when the operator invokes the runner, asks for flags, or needs to recover from an aborted runner run.

Bootstrap mode (running QPB on itself)

For a self-audit ("this is a bootstrap run", "run on itself"), read the bootstrap section of references/runner_mode.md. It also covers recovering from a partial or aborted run: git restore quality/, and never edit files outside quality/.

v1.5.4 mechanics (pointer-style, not duplicating the design doc)

Phase 1 also writes quality/exploration_role_map.json, and pipelines activate from that role map. Prior runs are archived under quality/previous_runs/ (legacy quality/runs/ stays readable). The details are in references/runner_mode.md; the phase prompts already encode them.

Guardrails (machine-checkable; treat as hard constraints)

These are not suggestions; the orchestrator enforces them and a violation aborts the run:

1. Synchronous execution — no sub-agent delegation. Run every phase yourself in the same session. Do NOT use the Task tool, sub-agent dispatch, background-agent invocations, or any "delegate phases 2–6 to a worker" pattern. The B-15 failure mode is real: Phase 1 completes, phases 2–6 silently die in a delegated agent that loses its parent session, the runner self-marks -PARTIAL, and the operator gets no signal anything was wrong. v1.5.4 prompts forbid this explicitly.
2. Don't patch QPB source mid-run. If you encounter a bug in bin/, .github/skills/, agents/, references/, SKILL.md, schemas.md, or AGENTS.md during the run, STOP and report: name the file:line, describe the failure, propose a fix shape — but do NOT apply the fix. The orchestrator captures a git-SHA baseline at run start and verifies the source tree unchanged at every phase boundary; an autonomous patch fails the gate with a diagnostic naming the modified files. Patches go through Council review, not mid-run improvisation.
3. Don't delete sentinel files. Files protected by .gitignore !-rules (e.g., reference_docs/.gitkeep, reference_docs/cite/.gitkeep) keep otherwise-empty tracked directories present. The pre-flight check enumerates every !-rule and aborts if any sentinel is missing. If you find such a file and don't understand its purpose, leave it alone.
4. Phase 1 file enumeration uses git ls-files. Use git ls-files as the canonical file list when the target is a git repo; this respects .gitignore automatically. Do NOT use os.walk, find, os.listdir, or any recursive directory walker — those pull in .git/, .venv/, node_modules/, build outputs, and vendored dependencies, all of which the role-map validator rejects. Disallowed path prefixes are .git/, .venv/, venv/, node_modules/, __pycache__/, .pytest_cache/, .mypy_cache/, .ruff_cache/, .tox/, plus any path whose components end in .egg-info or .dist-info. The role map carries a provenance field recording which enumeration source you used ("git-ls-files" or "filesystem-walk-with-skips" for non-git targets). There is also a 2000-entry ceiling; a role map exceeding it almost certainly walked .gitignored content.
5. Cross-artifact agreement. EXPLORATION.md's "File inventory" section and the role map's summary field both render from bin.role_map.summarize_role_map(). Don't write file counts or role percentages by hand; copy from the helper. The validator cross-checks the two and rejects mismatches.

If the operator's prompt says something that conflicts with these guardrails (e.g., "delegate phases 3–6 to a sub-agent so we can run faster"), don't comply with the conflicting instruction. Surface the conflict, name the guardrail, and ask for clarification. The guardrails exist because each one corresponds to a verified historical failure mode.

What this run produces — output artifact contract

A successful run produces this canonical set under the target's quality/ directory plus an AGENTS.md at the target's repo root. Every file listed here is gate-validated:

Path	Role
quality/EXPLORATION.md	Phase 1 findings — the foundation.
quality/exploration_role_map.json	Per-file role tagging from Phase 1.
quality/REQUIREMENTS.md	Testable requirements with use cases.
quality/QUALITY.md	Quality constitution.
quality/CONTRACTS.md	Behavioral contracts.
quality/COVERAGE_MATRIX.md	Requirement → test traceability.
quality/COMPLETENESS_REPORT.md	Final gate verdict.
quality/test_functional.*	Automated functional tests.
quality/RUN_CODE_REVIEW.md	Three-pass code review protocol.
quality/RUN_INTEGRATION_TESTS.md	Integration test protocol.
quality/RUN_SPEC_AUDIT.md	Council of Three spec audit protocol.
quality/RUN_TDD_TESTS.md	TDD red-green verification protocol.
quality/BUGS.md	Consolidated bug report.
quality/INDEX.md	Run metadata + role breakdown + gate verdict.
quality/PROGRESS.md	Phase-by-phase checkpoint log.
quality/previous_runs/<TIMESTAMP>/	Archive of any prior run.
quality/workspace/	Intermediate pipeline artifacts (control prompts, code reviews, spec audits, four-pass pipeline outputs, etc.).
AGENTS.md (target repo root)	Per-project orientation generated post-Phase-6. Carries a QPB sentinel marker so future runs detect QPB-managed copies.

The gate verdict in quality/INDEX.md (pass / partial / fail) is the operator-facing summary of how the run went. If it's anything other than pass, surface why before considering the run done.

Locating reference files

This skill references files in a references/ directory (e.g., references/iteration.md, references/review_protocols.md). The location depends on how the skill was installed. When a reference file is mentioned, resolve it by checking these paths in order and using the first one that exists:

1. references/ (relative to SKILL.md — works when running from the skill directory)
2. .claude/skills/quality-playbook/references/ (Claude Code installation)
3. .github/skills/references/ (GitHub Copilot flat installation)
4. .github/skills/quality-playbook/references/ (alternate Copilot installation)

All reference file mentions in this skill use the short form references/filename.md. If the relative path doesn't resolve, walk the fallback list above.

Why This Exists

Most software projects have tests, but few have a quality system. Tests check whether code works. A quality system answers harder questions: what does "working correctly" mean for this specific project? What are the ways it could fail that wouldn't be caught by tests? What should every developer (human or AI) know before touching this code?

Without a quality playbook, every new contributor (and every new AI session) starts from scratch — guessing at what matters, writing tests that look good but don't catch real bugs, and rediscovering failure modes that were already found and fixed months ago. A quality playbook makes the bar explicit, persistent, and inherited.

What This Skill Produces

Nine files that together form a repeatable quality system:

File	Purpose	Why It Matters	Executes Code?
quality/QUALITY.md	Quality constitution — coverage targets, fitness-to-purpose scenarios, theater prevention	Every AI session reads this first. It tells them what "good enough" means so they don't guess.	No
quality/REQUIREMENTS.md	Testable requirements with project overview, use cases, and narrative — generated by a five-phase pipeline (contract extraction → derivation → verification → completeness → narrative)	The foundation for Passes 2 and 3 of the code review. Without requirements, review is limited to structural anomalies (~65% ceiling). With them, the review can catch intent violations — absence bugs, cross-file contradictions, and design gaps that are invisible to code reading alone.	No
quality/test_functional.*	Automated functional tests derived from specifications	The safety net. Tests tied to what the spec says should happen, not just what the code does. Use the project's language: test_functional.py (Python), FunctionalSpec.scala (Scala), functional.test.ts (TypeScript), FunctionalTest.java (Java), etc.	Yes
quality/RUN_CODE_REVIEW.md	Three-pass code review protocol: structural review, requirement verification, cross-requirement consistency	Structural review alone misses ~35% of real defects. The three-pass pipeline adds requirement verification and consistency checking — backed by experiment evidence showing it finds bugs invisible to all structural review conditions.	No
quality/RUN_INTEGRATION_TESTS.md	Integration test protocol — end-to-end pipeline across all variants	Unit tests pass, but does the system actually work end-to-end with real external services?	Yes
quality/BUGS.md	Consolidated bug report with patches	Every confirmed bug in one place with reproduction details, spec basis, severity, and patch references. The single source of truth for what's broken and how to verify it.	No
quality/RUN_TDD_TESTS.md	TDD red-green verification protocol	Proves each bug is real (test fails on unpatched code) and each fix works (test passes after patch). Stronger evidence than a bug report alone — maintainers trust FAIL→PASS demonstrations.	Yes
quality/RUN_SPEC_AUDIT.md	Council of Three multi-model spec audit protocol	No single AI model catches everything. Three independent models with different blind spots catch defects that any one alone would miss.	No
AGENTS.md	Bootstrap context for any AI session working on this project	The "read this first" file. Without it, AI sessions waste their first hour figuring out what's going on.	No

Plus output directories: quality/code_reviews/, quality/spec_audits/, quality/results/, quality/history/.

The pipeline also generates supporting artifacts: quality/PROGRESS.md (phase-by-phase checkpoint log with cumulative BUG tracker), quality/CONTRACTS.md (behavioral contracts), quality/COVERAGE_MATRIX.md (traceability), quality/COMPLETENESS_REPORT.md (final gate), and quality/VERSION_HISTORY.md (review log). Phase 7 can additionally generate quality/REVIEW_REQUIREMENTS.md (interactive review protocol) and quality/REFINE_REQUIREMENTS.md (refinement pass protocol) for iterative improvement.

The two critical deliverables are the requirements file and the functional test file. The requirements file (quality/REQUIREMENTS.md) feeds the code review protocol's verification and consistency passes — it's what makes the code review catch more than structural anomalies. The functional test file (named for the project's language and test framework conventions) is the automated safety net. The Markdown protocols are documentation for humans and AI agents.

Complete Artifact Contract

quality_gate.py validates every artifact in the contract, including the v1.5.3 JSON manifests, sidecar JSON files, and run metadata. Read references/artifact_contract.md before writing any manifest, sidecar, or quality/results/run-*.json file: the gate checks field names and enum values, not just presence.

How to Use

The playbook is designed to run one phase at a time. Each phase runs in its own session with a clean context window, producing files on disk that the next phase reads. This gives much better results than running all phases at once — each phase gets the full context window for deep analysis instead of competing for space with other phases.

Default behavior: run Phase 1 only. When someone says "run the quality playbook" or "execute the quality playbook," run Phase 1 (Explore) and stop. After Phase 1 completes, tell the user what happened and what to say next. The user drives each phase forward explicitly.

Interactive protocol — how to guide the user

After every phase and every iteration, STOP and print guidance. Use a # header so it's prominent in the chat. The guidance must include: what just happened (one line), what the key outputs are, and the exact prompt to continue. See the end-of-phase messages defined after each phase section below.

If the user says "keep going", "continue", "next phase", "next", or anything similar, run the next phase in sequence. If all phases are complete, suggest the first iteration strategy (gap). If an iteration just finished, suggest the next strategy in the recommended cycle.

If the user says "run all phases", "run everything", or "run the full pipeline", run all phases sequentially in a single session. This uses more context but some users prefer it.

If the user asks "help", "how does this work", "what is this", or any similar phrasing, respond with this explanation (adapt the wording naturally, don't copy verbatim):

The Quality Playbook finds bugs that structural code review alone can't catch — the 35% of real defects that require understanding what the code is supposed to do. It works phase by phase:

• Phase 1 (Explore): Understand the codebase — architecture, risks, failure modes, specifications
• Phase 2 (Generate): Produce quality artifacts — requirements, tests, review protocols
• Phase 3 (Code Review): Three-pass review with regression tests for every confirmed bug
• Phase 4 (Spec Audit): Three independent AI auditors check the code against requirements
• Phase 5 (Reconciliation): Close the loop — TDD red-green verification for every bug
• Phase 6 (Verify): Self-check benchmarks validate all generated artifacts

After the numbered phases complete, you can run iteration strategies (gap, unfiltered, parity, adversarial) to find additional bugs — iterations typically add 40-60% more confirmed bugs on top of the baseline.

The playbook works best when you provide documentation alongside the code — specs, API docs, design documents, community documentation. It also gets significantly better results when you run each phase separately rather than all at once.

To get started, say: "Run the quality playbook on this project."

If the user asks "what happened", "what's going on", "where are we", or "what should I do next", read quality/PROGRESS.md and give them a concise status update: which phases are complete, how many bugs found so far, and what the next step is.

Documentation warning

At the start of Phase 1, before exploring any code, check for documentation. Look for directories named docs/, reference_docs/, doc/, documentation/, or any gathered documentation files. Also check if the user mentioned documentation in their prompt.

If no documentation is found, print this warning immediately (before proceeding):

Important: No project documentation found. The quality playbook works without documentation, but it finds significantly more bugs — and higher-confidence bugs — when you provide specs, API docs, design documents, or community documentation. In controlled experiments, documentation-enriched runs found different and better bugs than code-only baselines.

If you have documentation available, you can add it to a reference_docs/ directory and re-run Phase 1. Otherwise, I'll proceed with code-only analysis.

Then proceed with Phase 1 — don't block on this, just make sure the user sees the warning.

Running a specific phase

The user can request any individual phase:

Run quality playbook phase 1.
Run quality playbook phase 3 — code review.
Run phase 5 reconciliation.

When running a specific phase, check that its prerequisites exist (e.g., Phase 3 requires Phase 2 artifacts). If prerequisites are missing, tell the user which phases need to run first.

Iteration mode — improve on a previous run

Use this when a previous playbook run exists and you want to find additional bugs. Iteration mode replaces Phase 1's from-scratch exploration with a targeted exploration using one of five strategies, then merges findings with the previous run and re-runs Phases 2–6 against the combined results.

When to use iteration mode: After a complete playbook run, when you believe the codebase has more bugs than the first run found. This is especially effective for large codebases where a single run can only cover 3–5 subsystems, and for library/framework codebases where different exploration paths find different bug classes.

Read references/iteration.md for detailed strategy instructions. That file contains the full operational detail for each strategy, shared rules, merge steps, and the completion gate. The summary below describes when to use each strategy.

TDD applies to iteration runs. Every newly confirmed bug in an iteration run must go through the full TDD red-green cycle and produce quality/results/BUG-NNN.red.log (and .green.log if a fix patch exists). The quality gate enforces this — missing logs cause FAIL. See references/iteration.md shared rule 5 and the TDD Log Closure Gate in Phase 5.

Iteration strategies. The user selects a strategy by naming it in the prompt. If no strategy is named, default to gap.

Run the next iteration of the quality playbook.                          # default: gap strategy
Run the next iteration of the quality playbook using the gap strategy.
Run the next iteration using the unfiltered strategy.
Run the next iteration using the parity strategy.
Run an iteration using the adversarial strategy.

Recommended cycle: gap → unfiltered → parity → adversarial. Each strategy finds different bug classes:

• gap (default) — Scan previous coverage, explore uncovered subsystems and thin sections. Best when the first run was structurally sound but only covered a subset of the codebase.
• unfiltered — Pure domain-driven exploration with no structural constraints. No pattern templates, no applicability matrices, no section format requirements. Recovers bugs that structured exploration suppresses.
• parity — Systematically enumerate parallel implementations of the same contract (transport variants, fallback chains, setup-vs-reset paths) and diff them for inconsistencies. Finds bugs that only emerge from cross-path comparison.
• adversarial — Re-investigate dismissed/demoted triage findings and challenge thin SATISFIED verdicts. Recovers Type II errors from conservative triage.
• all — Runner-level convenience: executes gap → unfiltered → parity → adversarial in sequence, each as a separate agent session. Stops early if a strategy finds zero new bugs.

Phase-by-phase execution

Each phase produces files on disk that the next phase reads. This is how context transfers between phases — through files, not through conversation history. The key handoff files are:

• quality/EXPLORATION.md — Phase 1 writes this, Phase 2 reads it. Contains everything Phase 2 needs to generate artifacts without re-exploring the codebase.
• quality/PROGRESS.md — Updated after every phase. Cumulative BUG tracker ensures no finding is lost.
• Generated artifacts (REQUIREMENTS.md, CONTRACTS.md, etc.) — Phase 2 writes these, Phases 3–5 read them to run reviews, audits, and reconciliation.

The pattern for each phase boundary: finish the current phase, write everything to disk, then print the end-of-phase message and stop. When the user starts the next phase, read back the files you need before proceeding. This "write then read" cycle is the phase boundary — it lets you drop exploration context from working memory before loading review context, for example.

Write your Phase 1 exploration findings to quality/EXPLORATION.md before proceeding. This file is mandatory in all modes. Make it thorough: domain identification, architecture map, existing tests, specification summary, quality risks, skeleton/dispatch analysis, derived requirements (REQ-NNN), and derived use cases (UC-NN). Everything Phase 2 needs to generate artifacts must be in this file.

The discipline of writing exploration findings to disk is what forces thorough analysis. Without it, the model keeps vague impressions in working memory and produces broad, abstract requirements that miss function-level defects. Writing forces specificity: file paths, line numbers, exact function names, concrete behavioral rules. That specificity is what makes requirements precise enough to catch bugs during code review.

---

Run-state instrumentation (v1.5.6 — write events as you go)

Maintain quality/run_state.jsonl (append-only event log) and quality/PROGRESS.md (rewritten on every event) for the whole run. Before any phase work, read references/run_state_instrumentation.md for initialization, per-phase events, the artifact cross-checks required before each phase_end, and resume rules, plus references/run_state_schema.md for the event schema.

Phase 0: Prior Run Analysis (Automatic)

Runs only when quality/previous_runs/ holds prior artifacts, or when sibling versioned directories do (Phase 0b). It builds quality/SEED_CHECKS.md from prior confirmed bugs, checks each seed against the current tree, and feeds failing seeds into Phases 3 and 4. In Mode A, skip it. Otherwise read references/phase0_prior_runs.md.

Phase 1: Explore the Codebase (Write As You Go)

Read references/phase1_explore.md before exploring. It covers documentation intake, open domain-driven exploration, domain-knowledge risk analysis, the structured exploration patterns, deriving REQ-NNN requirements and UC-NN use cases, the exact quality/EXPLORATION.md section titles, and the mandatory Phase 1 completion gate. Write findings to disk as you go, then stop at the gate.

Phase 2: Generate the Quality Playbook

Read references/phase2_generate.md before generating. It holds the Phase 2 entry gate (13 checks on quality/EXPLORATION.md), the source-modification guardrail, JSON manifest rules, and the full spec for each generated file: QUALITY.md, functional tests, RUN_CODE_REVIEW.md, RUN_INTEGRATION_TESTS.md, RUN_SPEC_AUDIT.md, AGENTS.md (orchestrator-generated), RUN_TDD_TESTS.md, and the bug writeup template.

Phase 3: Code Review and Regression Tests

Run the three-pass review from quality/RUN_CODE_REVIEW.md against HEAD, then write a regression test and patch for every confirmed bug. Steps are in references/phase3_code_review.md.

Phase 4: Spec Audit and Triage

Three independent auditors check the code against the requirements, triage with verification probes, then run the Layer 2 semantic citation check into quality/citation_semantic_check.json. Steps are in references/phase4_spec_audit.md, together with references/spec_audit.md.

Phase 5: Post-Review Reconciliation and Closure Verification

Close the loop: every bug from review and audit is regression-tested or exempted, TDD red-green logs and sidecars are written, writeups exist for every confirmed bug, and quality_gate.py passes. Steps and closure gates are in references/phase5_reconcile.md.

Phase 6: Verify

Run the incremental self-check (steps 6.1 to 6.5), finalize PROGRESS.md, and, in continuation mode, the convergence check. Steps are in references/phase6_verify.md, and the full checklist is in references/verification.md.

Recheck Mode — Verify Bug Fixes

When the user says "recheck", "verify the bug fixes", or similar, re-test each bug in quality/BUGS.md against the current tree and write quality/results/recheck-results.json and recheck-summary.md. The procedure is in references/recheck_mode.md.

Phase 7: Present, Explore, Improve (Interactive)

Present a scannable summary table, offer drill-down on any artifact, and give a menu of improvement paths (iterations, requirement refinement, integration-test tuning). The format is in references/phase7_present.md.

Fixture Strategy

The quality/ folder is separate from the project's unit test folder. Create the appropriate test setup for the project's language:

• Python: quality/conftest.py for pytest fixtures. If fixtures are defined inline (common with pytest's tmp_path pattern), prefer that over shared fixtures.
• Java: A test class with @BeforeEach/@BeforeAll setup methods, or a shared test utility class.
• Scala: A trait mixed into test specs (e.g., trait FunctionalTestFixtures), or inline data builders.
• TypeScript/JavaScript: A quality/setup.ts with beforeAll/beforeEach hooks, or inline test factories.
• Go: Helper functions in the same _test.go file or a shared testutil_test.go. Use t.Helper() for test helpers. Go convention prefers inline test setup over shared fixtures.
• Rust: Helper functions in a #[cfg(test)] mod tests block, or a shared test_utils.rs module. Use builder patterns for test data.

Examine existing test files to understand how they set up test data. Whatever pattern the existing tests use, copy it. Study existing fixture patterns for realistic data shapes.

---

Terminology

• Functional testing — Does the code produce the output specs say it should? Distinct from unit testing (individual functions in isolation).
• Integration testing — Do components work together end-to-end, including real external services?
• Spec audit — AI models read code and compare against specs. No code executed. Catches where code doesn't match documentation.
• Coverage theater — Tests that produce high coverage numbers but don't catch real bugs. Example: asserting a function didn't throw without checking its output.
• Fitness-to-purpose — Does the code do what it's supposed to do under real-world conditions? A system can have 95% coverage and still lose records silently.

---

Principles

1. Fitness-to-purpose over coverage percentages
2. Scenarios come from code exploration AND domain knowledge
3. Concrete failure modes make standards non-negotiable — abstract requirements invite rationalization
4. Guardrails transform AI review quality (line numbers, read bodies, grep before claiming)
5. Triage before fixing — many "defects" are spec bugs or design decisions
6. Structural review has a ceiling (~65%). The remaining ~35% are intent violations — absence bugs, cross-file contradictions, design gaps — invisible to any tool that only reads code. Requirements make the invisible visible.
7. The specification is the unique contribution, not the review structure. Focus areas and review protocols are secondary to having the right testable requirements derived from intent sources.
8. Cross-requirement consistency checking is essential. Bugs often live in the gap between two individually-correct pieces of code. Per-requirement verification alone can't find these.
9. Keep all derived requirements — do not filter. The cost of checking an extra requirement is low; the cost of missing a bug because you pruned the requirement that would have caught it is high.
10. A failing test is the strongest evidence a bug exists. Run the red-green TDD cycle (test fails on buggy code, passes on fixed code) for every confirmed bug with a fix patch. Show the FAIL→PASS output — reviewers can disagree with your fix but can't argue with a reproducing test.

---

Reference Files

Read these as you work through each phase:

File	When to Read	Contains
references/run_state_instrumentation.md	Run start	Event log, PROGRESS.md upkeep, per-phase artifact cross-checks, resume rules
references/artifact_contract.md	Before writing manifests, sidecars, or run metadata	Complete artifact contract, sidecar JSON examples, run metadata format
references/runner_mode.md	Mode B, bootstrap runs, recovery	Runner invocation and flags, self-audit runs, v1.5.4 mechanics
references/phase0_prior_runs.md	Phase 0 / 0b	Seed checks from prior and sibling runs
references/phase1_explore.md	Phase 1	Exploration steps, EXPLORATION.md structure, Phase 1 completion gate
references/phase2_generate.md	Phase 2	Entry gate and the spec for every generated file
references/phase3_code_review.md	Phase 3	Code review run and regression tests
references/phase4_spec_audit.md	Phase 4	Spec audit run, triage, Layer 2 citation check
references/phase5_reconcile.md	Phase 5	Reconciliation, TDD closure, writeups, script-verified gate
references/phase6_verify.md	Phase 6	Incremental verification steps and convergence check
references/recheck_mode.md	Recheck	Re-testing bugs after fixes
references/phase7_present.md	Phase 7	Summary table, drill-down, improvement menu
references/exploration_patterns.md	Phase 1 (explore)	Pattern applicability matrix, deep-dive templates, domain-knowledge questions
references/defensive_patterns.md	Step 5 (finding skeletons)	Grep patterns, how to convert findings to scenarios
references/schema_mapping.md	Step 5b (schema types)	Field mapping format, mutation validity rules
references/requirements_pipeline.md	Phase 2 (requirements)	Five-phase pipeline, versioning protocol, carry-forward rules
references/constitution.md	File 1 (QUALITY.md)	Full template with section-by-section guidance
references/functional_tests.md	File 2 (functional tests)	Test structure, anti-patterns, cross-variant strategy
references/review_protocols.md	Files 3–4 (code review, integration)	Templates for both protocols, patch validation, skip guards
references/spec_audit.md	File 5 (Council of Three)	Full audit protocol, triage process, fix execution
references/iteration.md	Iterations (after Phase 6)	Four iteration strategies: gap, unfiltered, parity, adversarial
references/verification.md	Phase 6 (verify)	Complete self-check checklist (45 benchmarks) including structured output, patch gate, skip guard validation, pre-flight discovery, version stamps, bug writeups, enumeration completeness, triage executable evidence, code-extracted enumeration lists, mechanical verification artifacts, source-inspection test execution, contradiction gate, seed check execution, convergence tracking, sidecar JSON schema validation, script-verified closure gate, canonical use case identifiers, and writeup inline fix diffs