awesome-copilot/skills/quality-playbook/phase_prompts/phase5.md

{skill_fallback_guide}

You are a quality engineer continuing a phase-by-phase quality playbook run. Phases 1-4 are complete.

Read these files to get context:

1. quality/PROGRESS.md - run metadata, phase status, cumulative BUG tracker
2. quality/BUGS.md - all confirmed bugs from code review and spec audit
3. quality/REQUIREMENTS.md - derived requirements
4. SKILL.md - read the Phase 5 section ("Phase 5: Post-Review Reconciliation and Closure Verification"). Also read references/requirements_pipeline.md, references/review_protocols.md, and references/spec_audit.md. Resolve SKILL.md and the references/ directory via the documented fallback list above; do NOT assume any single install layout.

Execute Phase 5: Reconciliation + TDD + Closure.

1. Run the Post-Review Reconciliation per references/requirements_pipeline.md. Update COMPLETENESS_REPORT.md.

2. Run closure verification: every BUG in the tracker must have either a regression test or an explicit exemption.

3. Write bug writeups at quality/writeups/BUG-NNN.md for EVERY confirmed bug. The canonical template is the "Bug writeup generation" section of SKILL.md (resolve via the fallback list above) — read that section before writing. Use the exact field headings listed there: Summary, Spec reference, The code, Observable consequence, Depth judgment, The fix, The test, Related issues. Sections 1–4, 6, 7 are required in every writeup; section 5 (Depth judgment) fires only when the consequence isn't self-evident from the immediate code; section 8 (Related issues) is included only when related bugs exist. Do NOT introduce fields that aren't in the template (no "Minimal reproduction" as a top-level field, no "Patch path:" as a top-level field — those belong inside Spec reference and The test respectively).

   MANDATORY HYDRATION STEP. Before writing a writeup, re-open quality/BUGS.md and locate the ### BUG-NNN: entry for the bug you are about to write up. Every confirmed bug in BUGS.md already has the content you need — your job is to copy it into the writeup's sections, not to invent it. If a field is missing from BUGS.md, that is a reconciliation error to surface in PROGRESS.md, not a field to fabricate. Use this field map:

   BUGS.md field	Writeup section	How to use it
   Title line (### BUG-NNN:…)	Summary	One sentence naming the function/code path and the observable failure.
   Primary requirement	Spec reference	- Requirement: REQ-NNN
   Spec basis	Spec reference	- Spec basis: <doc path + line range(s), semicolon-separated if multiple> plus a ≤15-word contract quote copied verbatim from the cited lines.
   Location	The code	Cite file:line and describe what the current path does there.
   Minimal reproduction	Observable consequence	Weave into the consequence paragraph as the triggering input.
   Expected + Actual behavior	Observable consequence	The actual behavior is the observable failure; the expected defines the gap.
   Regression test	The test	- Regression test: <function name> — verbatim from BUGS.md.
   Patches (regression)	The test	- Regression patch: <path> — verbatim from BUGS.md.
   Patches (fix)	The fix + The test	If a fix patch file exists, read it and paste the unified diff inside ```diff; also list the patch path as - Fix patch: <path> under The test. If no fix patch exists (confirmed-open bug), write the minimal concrete unified diff directly in The fix anyway — SKILL.md requires an inline diff in every writeup. In the no-patch case, omit the Fix patch: bullet from The test.
   Red/green logs	The test	- Red receipt: quality/results/BUG-NNN.red.log and the matching green path.

   Worked example. The BUGS.md entry for BUG-004 is:

   ### BUG-004: naive upstream timestamps crash ETA math
   - Source: Code Review
   - Severity: HIGH
   - Primary requirement: REQ-006
   - Location: bus_tracker.py:138-144
   - Spec basis: quality/REQUIREMENTS.md:163-172; quality/QUALITY.md:57-65
   - Minimal reproduction: Return a visit whose ExpectedArrivalTime is an ISO string
     without timezone information, such as 2026-04-21T12:00:00.
   - Expected behavior: The affected arrival degrades to unknown-time while the rest
     of the stop remains usable.
   - Actual behavior: datetime.fromisoformat() returns a naive datetime and
     subtracting it from datetime.now(timezone.utc) raises TypeError, aborting the
     stop/request path.
   - Regression test: quality.test_regression.TestPhase3Regressions.test_bug_004_fetch_stop_arrivals_degrades_naive_timestamps
   - Patches: quality/patches/BUG-004-regression-test.patch, quality/patches/BUG-004-fix.patch
   

   The hydrated writeup sections look like this (sketch — paste the real diff from the fix patch file into ```diff, don't make one up):

   ## Summary
   fetch_stop_arrivals() crashes the whole stop/request path when an upstream visit
   carries a naive ExpectedArrivalTime, instead of degrading that arrival to
   unknown-time.
   
   ## Spec reference
   - Requirement: REQ-006
   - Spec basis: quality/REQUIREMENTS.md:163-172; quality/QUALITY.md:57-65
   - Behavioral contract quote: "degrade a bad per-arrival timestamp to unknown-time instead of aborting the whole response path"
   
   ## The code
   At bus_tracker.py:138-144, the parser calls datetime.fromisoformat(...) on
   ExpectedArrivalTime and subtracts the result from datetime.now(timezone.utc)…
   
   ## Observable consequence
   When the upstream visit returns ExpectedArrivalTime="2026-04-21T12:00:00"
   (no timezone), fromisoformat() returns a naive datetime, the subtraction
   raises TypeError, and the entire stop/request path aborts rather than the
   single affected arrival degrading to unknown-time.
   
   ## The fix
   ```diff
   <paste the real unified diff from quality/patches/BUG-004-fix.patch here>
   ```
   
   ## The test
   - Regression test: quality.test_regression.TestPhase3Regressions.test_bug_004_fetch_stop_arrivals_degrades_naive_timestamps
   - Regression patch: quality/patches/BUG-004-regression-test.patch
   - Fix patch: quality/patches/BUG-004-fix.patch
   - Red receipt: quality/results/BUG-004.red.log
   - Green receipt: quality/results/BUG-004.green.log
   

   Confirmation checklist (per writeup, before moving to the next bug). (a) Every required section has populated content copied from BUGS.md or the patch files — no empty backticks, no sentinel filler like "is a confirmed code bug in " or "The affected implementation lives at " or "Patch path: ``". (b) The ```diff fence contains at least one + or - line from the actual fix patch. (c) The Summary names a real function or code path, not the BUG identifier. (d) No angle-bracket placeholders (e.g., <...>) remain in the final writeup — those are pedagogical markers from the worked example and from SKILL.md, never acceptable output.

4. Run the TDD red-green cycle: for each confirmed bug, run the regression test against unpatched code -> quality/results/BUG-NNN.red.log. If a fix patch exists, run against patched code -> quality/results/BUG-NNN.green.log. If the test runner is unavailable, create the log with NOT_RUN on the first line.

5. Generate sidecar JSON: quality/results/tdd-results.json and quality/results/integration-results.json (schema_version "1.1", canonical fields: id, requirement, red_phase, green_phase, verdict, fix_patch_present, writeup_path).

6. If mechanical verification artifacts exist, run quality/mechanical/verify.sh and save receipts.

7. Run terminal gate verification, write it to PROGRESS.md.

MANDATORY CARDINALITY GATE (Lever 3, v1.5.2)

Before finalizing this phase, run the cardinality reconciliation gate against the current repo state. Locate quality_gate.py via the same fallback list used for SKILL.md (it sits in the same directory as SKILL.md in every install layout), then invoke it as a script — quality_gate.py runs check_v1_5_2_cardinality_gate(repo_dir) as part of its standard pass:

python3 <resolved_quality_gate_path> .

Where <resolved_quality_gate_path> is the first hit when walking the documented install-location fallback list, with SKILL.md swapped for quality_gate.py (e.g., quality_gate.py, .claude/skills/quality-playbook/quality_gate.py, .github/skills/quality_gate.py, .cursor/skills/quality-playbook/quality_gate.py, .continue/skills/quality-playbook/quality_gate.py, .github/skills/quality-playbook/quality_gate.py).

If the gate output contains any line beginning with cardinality gate:, or reports uncovered cells, malformed cell IDs, missing consolidation rationale on multi-cell Covers, or malformed downgrade records, STOP. Fix the BUGS.md entries or the compensation_grid_downgrades.json file. Do NOT proceed to completion until those failure lines no longer appear.

For every pattern-tagged REQ, the Phase 5 contract is:

• Every grid cell with "present": false appears in either a BUG's Covers: list or a downgrade record.
• Every Covers: entry uses the canonical cell ID form REQ-N/cell-<item>-<site>.
• Every BUG with ≥2 Covers: entries has a non-empty Consolidation rationale: line.
• Every downgrade record has cell_id, authority_ref, site_citation, reason_class (in the enum), falsifiable_claim (non-empty).

The cardinality gate is blocking. It is intentionally stricter than the Phase 3 advisory self-check; the advisory check is meant to surface problems early, but Phase 5 is where they become fatal.

Mark Phase 5 complete in PROGRESS.md (use the checkbox format - [x] Phase 5 - Reconciliation — do NOT switch to a table).

IMPORTANT: quality_gate.py will FAIL Phase 5 if any writeup is missing a non-empty ```diff block or contains any of these sentinel phrases verbatim: "is a confirmed code bug in ", "The affected implementation lives at ", "Patch path: ", "- Regression test: ", "- Regression patch: ``". Those two checks are the hard gate. Skipping the BUGS.md hydration step above is not gate-enforced but will produce writeups that read as unpopulated stubs and fail a human review — do not skip it.