Add quality-playbook skill

docs/README.skills.md

@@ -217,6 +217,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to
 | [publish-to-pages](../skills/publish-to-pages/SKILL.md) | Publish presentations and web content to GitHub Pages. Converts PPTX, PDF, HTML, or Google Slides to a live GitHub Pages URL. Handles repo creation, file conversion, Pages enablement, and returns the live URL. Use when the user wants to publish, deploy, or share a presentation or HTML file via GitHub Pages. | `scripts/convert-pdf.py`<br />`scripts/convert-pptx.py`<br />`scripts/publish.sh` |
 | [pytest-coverage](../skills/pytest-coverage/SKILL.md) | Run pytest tests with coverage, discover lines missing coverage, and increase coverage to 100%. | None |
 | [python-mcp-server-generator](../skills/python-mcp-server-generator/SKILL.md) | Generate a complete MCP server project in Python with tools, resources, and proper configuration | None |
+| [quality-playbook](../skills/quality-playbook/SKILL.md) | Explore any codebase from scratch and generate six quality artifacts: a quality constitution (QUALITY.md), spec-traced functional tests, a code review protocol, an integration testing protocol, a multi-model spec audit (Council of Three), and an AI bootstrap file (AGENTS.md). Works with any language (Python, Java, Scala, TypeScript, Go, Rust, etc.). Use this skill whenever the user asks to set up a quality playbook, generate functional tests from specifications, create a quality constitution, build testing protocols, audit code against specs, or establish a repeatable quality system for a project. Also trigger when the user mentions 'quality playbook', 'spec audit', 'Council of Three', 'fitness-to-purpose', 'coverage theater', or wants to go beyond basic test generation to build a full quality system grounded in their actual codebase. | `LICENSE.txt`<br />`references/constitution.md`<br />`references/defensive_patterns.md`<br />`references/functional_tests.md`<br />`references/review_protocols.md`<br />`references/schema_mapping.md`<br />`references/spec_audit.md`<br />`references/verification.md` |
 | [quasi-coder](../skills/quasi-coder/SKILL.md) | Expert 10x engineer skill for interpreting and implementing code from shorthand, quasi-code, and natural language descriptions. Use when collaborators provide incomplete code snippets, pseudo-code, or descriptions with potential typos or incorrect terminology. Excels at translating non-technical or semi-technical descriptions into production-quality code. | None |
 | [readme-blueprint-generator](../skills/readme-blueprint-generator/SKILL.md) | Intelligent README.md generation prompt that analyzes project documentation structure and creates comprehensive repository documentation. Scans .github/copilot directory files and copilot-instructions.md to extract project information, technology stack, architecture, development workflow, coding standards, and testing approaches while generating well-structured markdown documentation with proper formatting, cross-references, and developer-focused content. | None |
 | [refactor](../skills/refactor/SKILL.md) | Surgical code refactoring to improve maintainability without changing behavior. Covers extracting functions, renaming variables, breaking down god functions, improving type safety, eliminating code smells, and applying design patterns. Less drastic than repo-rebuilder; use for gradual improvements. | None |

skills/quality-playbook/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Andrew Stellman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

skills/quality-playbook/references/constitution.md

@@ -0,0 +1,160 @@
+# Writing the Quality Constitution (File 1: QUALITY.md)
+
+The quality constitution defines what "quality" means for this specific project and makes the bar explicit, persistent, and inherited by every AI session.
+
+## Template
+
+```markdown
+# Quality Constitution: [Project Name]
+
+## Purpose
+
+[2–3 paragraphs grounding quality in three principles:]
+
+- **Deming** ("quality is built in, not inspected in") — Quality is built into context files
+  and the quality playbook so every AI session inherits the same bar.
+- **Juran** ("fitness for use") — Define fitness specifically for this project. Not "tests pass"
+  but the actual real-world requirement. Example: "generates correct output that survives
+  input schema changes without silently producing wrong results."
+- **Crosby** ("quality is free") — Building a quality playbook upfront costs less than
+  debugging problems found after deployment.
+
+## Coverage Targets
+
+| Subsystem | Target | Why |
+|-----------|--------|-----|
+| [Most fragile module] | 90–95% | [Real edge case or past bug] |
+| [Core logic module] | 85–90% | [Concrete risk] |
+| [I/O or integration layer] | 80% | [Explain] |
+| [Configuration/utilities] | 75–80% | [Explain] |
+
+The rationale column is essential. It must reference specific risks or past failures.
+If you can't explain why a subsystem needs high coverage with a concrete example,
+the target is arbitrary.
+
+## Coverage Theater Prevention
+
+[Define what constitutes a fake test for this project.]
+
+Generic examples that apply to most projects:
+- Asserting a function returned *something* without checking what
+- Testing with synthetic data that lacks the quirks of real data
+- Asserting an import succeeded
+- Asserting mock returns what the mock was configured to return
+- Calling a function and only asserting no exception was thrown
+
+[Add project-specific examples based on what you learned during exploration.
+For a data pipeline: "counting output records without checking their values."
+For a web app: "checking HTTP 200 without checking the response body."
+For a compiler: "checking output compiles without checking behavior."]
+
+## Fitness-to-Purpose Scenarios
+
+[5–10 scenarios. Every scenario must include a `[Req: tier — source]` tag linking it to its requirement source. Use the template below:]
+
+### Scenario N: [Memorable Name]
+
+**Requirement tag:** [Req: formal — Spec §X] *(or `user-confirmed` / `inferred` — see SKILL.md Phase 1, Step 1 for tier definitions)*
+
+**What happened:** [The architectural vulnerability, edge case, or design decision.
+Reference actual code — function names, file names, line numbers. Frame as "this architecture permits the following failure mode."]
+
+**The requirement:** [What the code must do to prevent this failure.
+Be specific enough that an AI can verify it.]
+
+**How to verify:** [Concrete test or query that would fail if this regressed.
+Include exact commands, test names, or assertions.]
+
+---
+
+[Repeat for each scenario]
+
+## AI Session Quality Discipline
+
+1. Read QUALITY.md before starting work.
+2. Run the full test suite before marking any task complete.
+3. Add tests for new functionality (not just happy path — include edge cases).
+4. Update this file if new failure modes are discovered.
+5. Output a Quality Compliance Checklist before ending a session.
+6. Never remove a fitness-to-purpose scenario. Only add new ones.
+
+## The Human Gate
+
+[List things that require human judgment:]
+- Output that "looks right" (requires domain knowledge)
+- UX and responsiveness
+- Documentation accuracy
+- Security review of auth changes
+- Backward compatibility decisions
+```
+
+## Where Scenarios Come From
+
+Scenarios come from two sources — **code exploration** and **domain knowledge** — and the best scenarios combine both.
+
+### Source 1: Defensive Code Patterns (Code Exploration)
+
+Every defensive pattern is evidence of a past failure or known risk:
+
+1. **Defensive code** — Every `if value is None: return` guard is a scenario. Why was it needed?
+2. **Normalization functions** — Every function that cleans input exists because raw input caused problems
+3. **Configuration that could be hardcoded** — If a value is read from config instead of hardcoded, someone learned the value varies
+4. **Git blame / commit messages** — "Fix crash when X is missing" → Scenario: X can be missing
+5. **Comments explaining "why"** — "We use hash(id) not sequential index because..." → Scenario about correctness under that constraint
+
+### Source 2: What Could Go Wrong (Domain Knowledge)
+
+Don't limit yourself to what the code already defends against. Use your knowledge of similar systems to generate realistic failure scenarios that the code **should** handle. For every major subsystem, ask:
+
+- "What happens if this process is killed mid-operation?" (state machines, file I/O, batch processing)
+- "What happens if external input is subtly wrong?" (validation pipelines, API integrations)
+- "What happens if this runs at 10x scale?" (batch processing, databases, queues)
+- "What happens if two operations overlap?" (concurrency, file locks, shared state)
+- "What produces correct-looking output that is actually wrong?" (randomness, statistical operations, type coercion)
+
+These are not hypothetical — they are things that happen to every system of this type. Write them as **architectural vulnerability analyses**: "Because `save_state()` lacks an atomic rename pattern, a mid-write crash during a 10,000-record batch will leave a corrupted state file — the next run gets JSONDecodeError and cannot resume without manual intervention. At scale (9,240 records across 64 batches), this pattern risks silent loss of 1,693+ records with nothing to flag them as missing." Concrete numbers and specific consequences make scenarios authoritative and non-negotiable. An AI session reading "records can be lost" will argue the standard down. An AI session reading a specific failure mode with quantified impact will not.
+
+### The Narrative Voice
+
+Each scenario's "What happened" must read like an architectural vulnerability analysis, not an abstract specification. Include:
+
+- **Specific quantities** — "308 records across 64 batches" not "some records"
+- **Cascade consequences** — "cascading through all subsequent pipeline steps, requiring reprocessing of 4,300 records instead of 308"
+- **Detection difficulty** — "nothing would flag them as missing" or "only statistical verification would catch it"
+- **Root cause in code** — "`random.seed(index)` creates correlated sequences because sequential integers produce related random streams"
+
+The narrative voice serves a critical purpose: it makes standards non-negotiable. Abstract requirements ("records should not be lost") invite rationalization. Specific failure modes with quantified impact ("a mid-batch crash silently loses 1,693 records with no detection mechanism") do not. Frame these as "this architecture permits the following failure" — grounded in the actual code, not fabricated as past incidents.
+
+### Combining Both Sources
+
+The strongest scenarios combine a defensive pattern found in code with domain knowledge about why it matters:
+
+1. Find the defensive code: `save_state()` writes to a temp file then renames
+2. Ask what failure this prevents: mid-write crash leaves corrupted state file
+3. Write the scenario as a vulnerability analysis: "Without the atomic rename pattern, a crash mid-write leaves state.json 50% complete. The next run gets JSONDecodeError and cannot resume without manual intervention."
+4. Ground it in code: "Read persistence.py line ~340: verify temp file + rename pattern"
+
+### The "Why" Requirement
+
+Every coverage target, every quality gate, every standard must have a "why" that references a specific scenario or risk. Without rationale, a future AI session will optimize for speed and argue the standard down.
+
+Bad: "Core logic: 100% coverage"
+Good: "Core logic: 100% — because `random.seed(index)` created correlated sequences that produced 77.5% bias instead of 50/50. Subtle bugs here produce plausible-but-wrong output. Only statistical verification catches them."
+
+The "why" is not documentation — it is protection against erosion.
+
+## Calibrating Scenario Count
+
+Aim for 2+ scenarios per core module (the modules identified as most complex or fragile). For a medium-sized project, this typically yields 8–10 scenarios. Fewer is fine for small projects; more for complex ones. If you're finding very few scenarios, it usually means the exploration was shallow rather than the project being simple — go back and read function bodies more carefully. Quality matters more than count: one scenario that precisely captures an architectural vulnerability is worth more than three generic "what if the input is bad" scenarios.
+
+## Self-Critique Before Finishing
+
+After drafting all scenarios, review each one and ask:
+
+1. **"Would an AI session argue this standard down?"** If yes, the "why" isn't concrete enough. Add numbers, consequences, and detection difficulty.
+2. **"Does the 'What happened' read like a vulnerability analysis or an abstract spec?"** If it reads like a spec, rewrite it with specific quantities, cascading consequences, and grounding in actual code.
+3. **"Is there a scenario I'm not seeing?"** Think about what a different AI model would flag. Architecture models catch data flow problems. Edge-case models catch boundary conditions. What are you blind to?
+
+## Critical Rule
+
+Each scenario's "How to verify" section must map to at least one automated test in the functional test file. If a scenario can't be automated, note why (it may require the Human Gate) — but most scenarios should be testable.

skills/quality-playbook/references/defensive_patterns.md

@@ -0,0 +1,140 @@
+# Finding Defensive Patterns (Step 5)
+
+Defensive code patterns are evidence of past failures or known risks. Every null guard, try/catch, normalization function, and sentinel check exists because something went wrong — or because someone anticipated it would. Your job is to find these patterns systematically and convert them into fitness-to-purpose scenarios and boundary tests.
+
+## Systematic Search
+
+Don't skim — grep the codebase methodically. The exact patterns depend on the project's language. Here are common defensive-code indicators grouped by what they protect against:
+
+**Null/nil guards:**
+
+| Language | Grep pattern |
+|---|---|
+| Python | `None`, `is None`, `is not None` |
+| Java | `null`, `Optional`, `Objects.requireNonNull` |
+| Scala | `Option`, `None`, `.getOrElse`, `.isEmpty` |
+| TypeScript | `undefined`, `null`, `??`, `?.` |
+| Go | `== nil`, `!= nil`, `if err != nil` |
+| Rust | `Option`, `unwrap`, `.is_none()`, `?` |
+
+**Exception/error handling:**
+
+| Language | Grep pattern |
+|---|---|
+| Python | `except`, `try:`, `raise` |
+| Java | `catch`, `throws`, `try {` |
+| Scala | `Try`, `catch`, `recover`, `Failure` |
+| TypeScript | `catch`, `throw`, `.catch(` |
+| Go | `if err != nil`, `errors.New`, `fmt.Errorf` |
+| Rust | `Result`, `Err(`, `unwrap_or`, `match` |
+
+**Internal/private helpers (often defensive):**
+
+| Language | Grep pattern |
+|---|---|
+| Python | `def _`, `__` |
+| Java/Scala | `private`, `protected` |
+| TypeScript | `private`, `#` (private fields) |
+| Go | lowercase function names (unexported) |
+| Rust | `pub(crate)`, non-`pub` functions |
+
+**Sentinel values, fallbacks, boundary checks:** Search for `== 0`, `< 0`, `default`, `fallback`, `else`, `match`, `switch` — these are language-agnostic.
+
+## What to Look For Beyond Grep
+
+- **Bugs that were fixed** — Git history, TODO comments, workarounds, defensive code that checks for things that "shouldn't happen"
+- **Design decisions** — Comments explaining "why" not just "what." Configuration that could have been hardcoded but isn't. Abstractions that exist for a reason.
+- **External data quirks** — Any place the code normalizes, validates, or rejects input from an external system
+- **Parsing functions** — Every parser (regex, string splitting, format detection) has failure modes. What happens with malformed input? Empty input? Unexpected types?
+- **Boundary conditions** — Zero values, empty strings, maximum ranges, first/last elements, type boundaries
+
+## Converting Findings to Scenarios
+
+For each defensive pattern, ask: "What failure does this prevent? What input would trigger this code path?"
+
+The answer becomes a fitness-to-purpose scenario:
+
+```markdown
+### Scenario N: [Memorable Name]
+
+**Requirement tag:** [Req: inferred — from function_name() behavior] *(use the canonical `[Req: tier — source]` format from SKILL.md Phase 1, Step 1)*
+
+**What happened:** [The failure mode this code prevents. Reference the actual function, file, and line. Frame as a vulnerability analysis, not a fabricated incident.]
+
+**The requirement:** [What the code must do to prevent this failure.]
+
+**How to verify:** [A concrete test that would fail if this regressed.]
+```
+
+## Converting Findings to Boundary Tests
+
+Each defensive pattern also maps to a boundary test:
+
+```python
+# Python (pytest)
+def test_defensive_pattern_name(fixture):
+    """[Req: inferred — from function_name() guard] guards against X."""
+    # Mutate fixture to trigger the defensive code path
+    # Assert the system handles it gracefully
+```
+
+```java
+// Java (JUnit 5)
+@Test
+@DisplayName("[Req: inferred — from methodName() guard] guards against X")
+void testDefensivePatternName() {
+    fixture.setField(null);  // Trigger defensive code path
+    var result = process(fixture);
+    assertNotNull(result);  // Assert graceful handling
+}
+```
+
+```scala
+// Scala (ScalaTest)
+// [Req: inferred — from methodName() guard]
+"defensive pattern: methodName()" should "guard against X" in {
+  val input = fixture.copy(field = None)  // Trigger defensive code path
+  val result = process(input)
+  result should equal (defined)  // Assert graceful handling
+}
+```
+
+```typescript
+// TypeScript (Jest)
+test('[Req: inferred — from functionName() guard] guards against X', () => {
+    const input = { ...fixture, field: null };  // Trigger defensive code path
+    const result = process(input);
+    expect(result).toBeDefined();  // Assert graceful handling
+});
+```
+
+```go
+// Go (testing)
+func TestDefensivePatternName(t *testing.T) {
+    // [Req: inferred — from FunctionName() guard] guards against X
+    t.Helper()
+    fixture.Field = nil  // Trigger defensive code path
+    result, err := Process(fixture)
+    if err != nil {
+        t.Fatalf("expected graceful handling, got error: %v", err)
+    }
+    // Assert the system handled it
+}
+```
+
+```rust
+// Rust (cargo test)
+#[test]
+fn test_defensive_pattern_name() {
+    // [Req: inferred — from function_name() guard] guards against X
+    let input = Fixture { field: None, ..default_fixture() };
+    let result = process(&input);
+    assert!(result.is_ok(), "expected graceful handling");
+}
+```
+
+## Minimum Bar
+
+You should find at least 2–3 defensive patterns per source file in the core logic modules. If you find fewer, read function bodies more carefully — not just signatures and comments.
+
+For a medium-sized project (5–15 source files), expect to find 15–30 defensive patterns total. Each one should produce at least one boundary test.