"Do you have exported AI chat history from developing this project — Claude exports, Gemini takeouts, ChatGPT exports, Claude Code transcripts, or similar? If so, point me to the folder. The design discussions, incident reports, and quality decisions in those chats will make the generated quality playbook significantly better."

1. Scan for an index file first. Look for files named

   INDEX*

   ,

   CONTEXT.md

   ,

   README.md

   , or similar navigation aids. If one exists, read it — it will tell you what's there and how to find things.
2. Search for quality-relevant conversations. Look for messages mentioning: quality, testing, coverage, bugs, failures, incidents, crashes, validation, retry, recovery, spec, fitness, audit, review. Also search for the project name.
3. Extract design decisions and incident history. The most valuable content is: (a) incident reports — what went wrong, how many records affected, how it was detected, (b) design discussions — why a particular approach was chosen, what alternatives were rejected, (c) quality framework discussions — coverage targets, testing philosophy, model review experiences, (d) cross-model feedback — where different AI models disagreed about the code.
4. Don't try to read everything. Chat histories can be enormous. Use the index to find the most relevant conversations, then search within those for quality-related content. 10 minutes of targeted searching beats 2 hours of exhaustive reading.

pyproject.toml

package.json

Cargo.toml

• What does this project do? (One sentence.)
• What language and key dependencies?
• What external systems does it talk to?
• What is the primary output?

AGENTS.md

CLAUDE.md

specs/

docs/

spec/

design/

architecture/

adr/

.md

1. Ask the user — they often know the requirements even if they're not written down.
2. README and inline documentation — many projects embed requirements in their README, API docs, or code comments.
3. Existing test suite — tests are implicit specifications. If a test asserts

   process(x) == y

   , that's a requirement.
4. Type signatures and validation rules — schemas, type annotations, and validators define what the system accepts and rejects.
5. Infer from code behavior — as a last resort, read the code and infer what it's supposed to do. Mark these as inferred requirements in QUALITY.md and flag them for user confirmation.

• [Req: formal — README §3]

  — written by humans in a spec document. Authoritative.

• [Req: user-confirmed — "must handle empty input"]

  — stated by the user but not in a formal doc. Treat as authoritative.

• [Req: inferred — from validate_input() behavior]

  — deduced from code. Flag for user review.

• The 3–5 major subsystems
• The data flow (Input → Processing → Output)
• The most complex module
• The most fragile module

1. Read the actual function signatures — parameter names, types, defaults. Don't guess from usage context — read the function definition and any documentation (Python docstrings, Java/Scala Javadoc/ScalaDoc, TypeScript type annotations, Go godoc comments, Rust doc comments and type signatures).
2. Read real data files — If the project has items files, fixture files, config files, or sample data (in

   pipelines/

   ,

   fixtures/

   ,

   test_data/

   ,

   examples/

   ), read them. Your test fixtures must match the real data shape exactly.
3. Read existing test fixtures — How do existing tests create test data? Copy their patterns. If they build config dicts with specific keys, use those exact keys.
4. Check library versions — Check the project's dependency manifest (

   requirements.txt

   ,

   build.sbt

   ,

   package.json

   ,

   pom.xml

   /

   build.gradle

   ,

   go.mod

   ,

   Cargo.toml

   ) to see what's actually available. Don't write tests that depend on library features that aren't installed. If a dependency might be missing, use the test framework's skip mechanism — see

   references/functional_tests.md

   § "Library version awareness" for framework-specific examples.

• What does "silently wrong" look like for this project?
• What external dependencies can change without warning?
• What looks simple but is actually complex?
• Where do cross-cutting concerns hide?

• "What goes wrong in systems like this?" — If it's a batch processor, think about crash recovery, idempotency, silent data loss, state corruption. If it's a web app, think about auth edge cases, race conditions, input validation bypasses. If it handles randomness or statistics, think about seeding, correlation, distribution bias.
• "What produces correct-looking output that is actually wrong?" — This is the most dangerous class of bug: output that passes all checks but is subtly corrupted.
• "What happens at 10x scale that doesn't happen at 1x?" — Chunk boundaries, rate limits, timeout cascading, memory pressure.
• "What happens when this process is killed at the worst possible moment?" — Mid-write, mid-transaction, mid-batch-submission.

save_state()

references/constitution.md

1. Purpose — What quality means for this project, grounded in Deming (built in, not inspected), Juran (fitness for use), Crosby (quality is free). Apply these specifically: what does "fitness for use" mean for this system? Not "tests pass" but the actual operational requirement.
2. Coverage Targets — Table mapping each subsystem to a target with rationale referencing real risks. Every target must have a "why" grounded in a specific scenario — without it, a future AI session will argue the target down.
3. Coverage Theater Prevention — Project-specific examples of fake tests, derived from what you saw during exploration. (Why: AI-generated tests often pad coverage numbers without catching real bugs — asserting that imports worked, that dicts have keys, or that mocks return what they were configured to return. Calling this out explicitly stops the pattern.)
4. Fitness-to-Purpose Scenarios — The heart of it. Each scenario documents a realistic failure mode with code references and verification method. Aim for 2+ scenarios per core module — typically 8–10 total for a medium project, fewer for small projects, more for complex ones. Quality matters more than count: a scenario that precisely captures a real architectural vulnerability is worth more than three generic ones. (Why: Coverage percentages tell you how much code ran, not whether it ran correctly. A system can have 95% coverage and still lose records silently. Fitness scenarios define what "working correctly" actually means in concrete terms that no one can argue down.)
5. AI Session Quality Discipline — Rules every AI session must follow
6. The Human Gate — Things requiring human judgment

save_state()

references/functional_tests.md

• Spec requirements — One test per testable spec section. Each test's documentation cites the spec requirement it verifies.
• Fitness scenarios — One test per QUALITY.md scenario. 1:1 mapping, named to match.
• Boundaries and edge cases — One test per defensive pattern from Step 5.

• Match the existing import pattern exactly. Read how existing tests import project modules and do the same thing. Getting this wrong means every test fails.
• Read every function's signature before calling it. Read the actual

  def

  line — parameter names, types, defaults. Read real data files from the project to understand data shapes. Do not guess at function parameters or fixture structures.
• No placeholder tests. Every test must import and call actual project code. If the body is

  pass

  or the assertion is trivial (

  assert isinstance(x, list)

  ), delete it. A test that doesn't exercise project code inflates the count and creates false confidence.
• Test count heuristic = (testable spec sections) + (QUALITY.md scenarios) + (defensive patterns). For a medium project (5–15 source files), this typically yields 35–50 tests. Significantly fewer suggests missed requirements or shallow exploration. Significantly more is fine if every test is meaningful — don't pad to hit a number.
• Cross-variant heuristic: ~30% — If the project handles multiple input types, aim for roughly 30% of tests parametrized across all variants. The exact percentage matters less than ensuring every cross-cutting property is tested across all variants.
• Test outcomes, not mechanisms — Assert what the spec says should happen, not how the code implements it.
• Use schema-valid mutations — Boundary tests must use values the schema accepts (from Step 5b), not values it rejects.

references/review_protocols.md

• Line numbers are mandatory — no line number, no finding
• Read function bodies, not just signatures
• If unsure: flag as QUESTION, not BUG
• Grep before claiming missing
• Do NOT suggest style changes — only flag things that are incorrect

references/verification.md

1. Test count near heuristic target (spec sections + scenarios + defensive patterns)
2. Scenario coverage — scenario test count matches QUALITY.md scenario count
3. Cross-variant coverage — ~30% of tests parametrize across all input variants
4. Boundary test count ≈ defensive pattern count from Step 5
5. Assertion depth — Majority of assertions check values, not just presence
6. Layer correctness — Tests assert outcomes (what spec says), not mechanisms (how code implements)
7. Mutation validity — Every fixture mutation uses a schema-valid value from Step 5b
8. All tests pass — zero failures AND zero errors. Run the test suite using the project's test runner (Python:

   pytest -v

   , Scala:

   sbt testOnly

   , Java:

   mvn test

   /

   gradle test

   , TypeScript:

   npx jest

   , Go:

   go test -v

   , Rust:

   cargo test

   ) and check the summary. Errors from missing fixtures, failed imports, or unresolved dependencies count as broken tests. If you see setup errors, you forgot to create the fixture/setup file or referenced undefined test helpers.
9. Existing tests unbroken — The new files didn't break anything.
10. Integration test quality gates were written from a Field Reference Table. Verify that you built a Field Reference Table by re-reading each schema file before writing quality gates, and that every field name in the quality gates is copied from that table — not from memory. If you skipped the table, go back and build it now.

Here's what I generated:

| File | What It Does | Key Metric | Confidence |
|------|-------------|------------|------------|
| QUALITY.md | Quality constitution | 10 scenarios | ██████░░ High — grounded in code, but scenarios are inferred, not from real incidents |
| Functional tests | Automated tests | 47 passing | ████████ High — all tests pass, 35% cross-variant |
| RUN_CODE_REVIEW.md | Code review protocol | 8 focus areas | ████████ High — derived from architecture |
| RUN_INTEGRATION_TESTS.md | Integration test protocol | 9 runs × 3 providers | ██████░░ Medium — quality gates need threshold tuning |
| RUN_SPEC_AUDIT.md | Council of Three audit | 10 scrutiny areas | ████████ High — guardrails included |
| AGENTS.md | AI session bootstrap | Updated | ████████ High — factual |

• High — Derived directly from code, specs, or schemas. Unlikely to need revision.
• Medium — Reasonable inference, but could be wrong. Benefits from user input.
• Low — Best guess. Definitely needs user input to be useful.

To use these artifacts, start a new AI session and try one of these prompts:

• Run a code review:
  "Read quality/RUN_CODE_REVIEW.md and follow its instructions to review [module or file]."

• Run the functional tests:
  "[test runner command, e.g. pytest quality/ -v, mvn test -Dtest=FunctionalTest, etc.]"

• Run the integration tests:
  "Read quality/RUN_INTEGRATION_TESTS.md and follow its instructions."

• Start a spec audit (Council of Three):
  "Read quality/RUN_SPEC_AUDIT.md and follow its instructions using [model name]."

"You can ask me about any of these to see the details — for example, 'show me Scenario 3' or 'walk me through the integration test matrix.'"

• "Tell me about Scenario 4" → Show the scenario text, explain where it came from (which defensive pattern or domain knowledge), and flag what you inferred vs. what you know.
• "Show me the integration test matrix" → Show the run groups, explain the parallelism strategy, and note which quality gates you derived from schemas vs. guessed at.
• "How do the functional tests work?" → Show the three test groups, explain the mapping to specs and scenarios, and highlight any tests you're least confident about.

"Three ways to make this better:"

1. Review and harden individual items — Pick any scenario, test, or protocol section and I'll walk through it with you. Good for: tightening specific quality gates, fixing inferred scenarios, adding missing edge cases.

2. Guided Q&A — I'll ask you 3-5 targeted questions about things I couldn't infer from the code: incident history, expected distributions, cost tolerance, model preferences. Good for: filling knowledge gaps that make scenarios more authoritative.

3. Review development history — Point me to exported AI chat history (Claude, Gemini, ChatGPT exports, Claude Code transcripts) and I'll mine it for design decisions, incident reports, and quality discussions that should be in QUALITY.md. Good for: grounding scenarios in real project history instead of inference.

"You can do any combination of these, in any order. Which would you like to start with?"

• Incident history for scenarios. "I found [specific defensive code]. What failure caused this? How many records were affected?"
• Quality gate thresholds. "I'm checking that [field] contains [values]. What distribution is normal? What signals a problem?"
• Integration test scale and cost. "The protocol runs [N] tests costing roughly $[X]. Should I increase or decrease coverage?"
• Test scope. "I generated [N] functional tests. Your existing suite covers [other areas]. Are there gaps?"
• Model preferences for spec audit. "Which AI models do you use? Have you noticed specific strengths?"

1. Scan for index files and navigate to quality-relevant conversations (same approach as Step 0, but now with specific targets — you know which scenarios need grounding, which quality gates need thresholds, which design decisions need rationale).
2. Extract: incident stories with specific numbers, design rationale for defensive patterns, quality framework discussions, cross-model audit results.
3. Revise QUALITY.md scenarios with real incident details. Update integration test thresholds with real-world values. Add Council of Three empirical data if audit results exist.
4. Re-run tests after revisions.

quality/

• 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.

• 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.

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