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

You are a quality engineer. {skill_fallback_guide} For this phase read ONLY the sections up through Phase 1 (stop at the "---" line before "Phase 2"). Also read the reference files (under whichever references/ directory matches the install path you resolved) that are relevant to exploration.

{seed_instruction}

Execute Phase 1: Explore the codebase. The reference_docs/ directory contains gathered documentation - read it to supplement your exploration. Top-level files are Tier 4 context (AI chats, design notes, retrospectives). Files under reference_docs/cite/ are citable sources (project specs, RFCs). If reference_docs/ is missing or empty, proceed with Tier 3 evidence (source tree) alone and note this in EXPLORATION.md.

MANDATORY FILE-ROLE TAGGING (v1.5.4 Part 1)

Before (or as part of) writing EXPLORATION.md, produce quality/exploration_role_map.json. Begin by reading SKILL.md at the repository root if present (also check for any other top-level skill-shaped entry file — the indicator is content + name, not extension; a README.md is NOT a skill-shaped entry just because it sits at the root). The prose context informs every subsequent file's role tag.

File source (v1.5.4 Phase 3.6.1, codex-prevention). Use git ls-files as the canonical file list when the target is a git repo — this respects .gitignore automatically and is the ONLY supported enumeration source. Do NOT use os.walk, find, os.listdir, or any recursive directory walker — those will pull in .git/, .venv/, node_modules/, build outputs, and vendored dependencies, all of which are FORBIDDEN in the role map (the validator rejects them and aborts the run). When the target is not a git repo, use a filesystem walk that explicitly skips the disallowed paths listed below; record this fallback in the role map's provenance field.

Disallowed paths (MUST NOT appear in the role map under any role): .git/, .venv/, venv/, node_modules/, __pycache__/, .pytest_cache/, .mypy_cache/, .ruff_cache/, .tox/, plus any path with a component ending in .egg-info or .dist-info. The validator at bin/role_map.py::DISALLOWED_PATH_PREFIXES enforces this — if your role map contains any such path, the run aborts. There is also a hard ceiling of 2000 entries; a role map with more is treated as evidence Phase 1 walked .gitignored content.

Provenance (v1.5.4 Phase 3.6.1). The role map's top-level provenance field MUST be one of:

• "git-ls-files" — preferred. Target is a git repo; you ran git ls-files to enumerate.
• "filesystem-walk-with-skips" — fallback. Target is not a git repo; you walked the filesystem with explicit skips for every entry in the disallowed-paths list above.
• "unknown" — accepted only on legacy role maps; do NOT emit this for fresh runs.

For each in-scope file, emit a record with the role taxonomy below. The judgment is content-based: read the file (or enough of it to judge), do NOT pattern-match on extension or directory name alone.

Sentinel files (v1.5.4 Phase 3.6.1). Files named .gitkeep (or similar empty-directory markers) in the repository's tracked tree MUST NOT be deleted. They keep otherwise-empty directories present in git history. If you find such a file and don't understand its purpose, leave it alone. The pre-flight check verifies all .gitignore !-rule sentinels are present and aborts the run if any are missing.

If you encounter a bug in QPB itself during this run (e.g., an exception from bin/run_playbook.py, a missing import, a broken assertion in QPB source), STOP the run immediately and report:

1. The exact error and where it occurred (file:line + traceback)
2. A diagnosis of the likely root cause
3. A proposed fix shape (do NOT apply it)

Do NOT patch QPB source code yourself. QPB source changes go through Council review (see ~/Documents/AI-Driven Development/CLAUDE.md). A structural backstop captures the QPB source tree's git SHA at run start and verifies it unchanged at every phase boundary; an autonomous source patch will fail the gate with a diagnostic naming the modified files.

Role taxonomy (single source of truth: bin/role_map.py::ROLE_DESCRIPTIONS): {role_taxonomy}

If a file genuinely doesn't fit any of these, you may add a new role — but document the addition in your role map's first entry as a comment-style rationale.

The output file quality/exploration_role_map.json MUST conform to this schema:

{{
  "schema_version": "1.0",
  "timestamp_start": "<ISO 8601 UTC timestamp at the start of Phase 1>",
  "provenance": "git-ls-files",
  "files": [
    {{
      "path": "<repo-relative POSIX path>",
      "role": "<one of the role taxonomy values>",
      "size_bytes": <int>,
      "rationale": "<one or two sentences justifying the tag, content-based>"
    }}
    // ... one entry per in-scope file. When role == "skill-tool", also
    // include a "skill_prose_reference" string pointing at the SKILL.md /
    // reference-file location that names this script (e.g., "SKILL.md:47"
    // or "references/forms.md:section-3"); the prose-to-code divergence
    // check in Phase 4 reads this back to find the cited prose.
  ]
}}

You only produce files[] and provenance. The two mechanically-derivable fields — breakdown and summary — are computed by the runner between Phase 1 LLM exit and the Phase 2 entry-gate (v1.5.6 cluster 047 architectural fix). The runner calls bin.role_map.compute_breakdown(files) and bin.role_map.summarize_role_map(...) and writes the canonical values into the on-disk file before validation. Don't include breakdown or summary in your output — even if you do, the runner will overwrite them. Your job is the analytical work (per-file role tagging in files[] plus provenance); the deterministic aggregations are runner-owned. (Pre-v1.5.6 the LLM was instructed to compute these too, which produced a class of failures where the LLM reverted to intuitive summarization that drifted from the strict mechanical contract; runner-side computation removes the failure mode.)

Tagging discipline:

1. skill-tool and code is the load-bearing distinction. A script is only skill-tool if SKILL.md (or a doc SKILL.md cites) explicitly names it and tells the agent to invoke it. Independent code modules — even small ones in a scripts/ directory — are code if no SKILL.md prose directs the agent to use them.
2. Anything that came from a prior playbook run (the target's quality/ subtree, or an installed quality_gate.py from QPB itself — the file the installer copies next to SKILL.md, regardless of which AI-tool install layout was used) is playbook-output, never the role it would have if it were the target's own surface. This prevents the v1.5.3 LOC-pollution failure mode where a target's apparent code surface was inflated by QPB's own infrastructure.
3. If SKILL.md is absent at the root and no other skill-shaped entry file exists, the role map will have zero skill-prose entries. That's fine — the four-pass derivation pipeline will no-op for this target.

Handling edge cases (v1.5.4 Phase 1 edge-case discipline):

• No SKILL.md at root, no other skill-shaped entry. Tag every file by content as usual. The role map will carry zero skill-prose and skill-reference entries; the four-pass pipeline will no-op. Do NOT invent a synthetic SKILL.md or label something skill-prose for a project that genuinely has no skill surface.
• SKILL.md references a script that does not exist. Add a top-level broken_references array to the role map carrying {{"prose_location": "<file>:<line>", "missing_script": "<path-as-cited>"}} entries. Do NOT add a synthetic file entry for the missing script. Note the broken reference in EXPLORATION.md so Phase 4's prose-to-code divergence check can register it as a known gap. (This field is additive; the gate's role-map validator does not require it.)
• Target with a very large file count (1000+). Process in batches. The files array can grow incrementally as you walk the tree; once you've made all per-file judgments, write the file once. Do not write a partial role map mid-walk — the validator considers the file complete when it appears, and the runner-side normalize_role_map_for_gate step (v1.5.6 cluster 047) computes breakdown and summary after you exit Phase 1.
• Ambiguous prose ("the helper script", "the validator"). Default to code. skill-tool requires an unambiguous citation: SKILL.md or a referenced doc must name the file (or a path-suffix that uniquely identifies it) AND direct the agent to invoke it. When in doubt, tag code and capture the ambiguity in rationale — it's better to under-tag skill-tool than to inflate the surface area Phase 4's prose-to-code check operates on.
• Generated files (build outputs, vendored dependencies, lockfiles). Skip them at the ignore-rule layer; do not include them in the role map. If you can't tell whether a file is generated, look for a generation marker (header comment naming the generator, sibling .generated file, presence in .gitignore); if generated, omit from the role map.

When Phase 1 is complete, write your full exploration findings to quality/EXPLORATION.md. The file MUST contain ALL of the following section titles VERBATIM (the Phase 1 gate at SKILL.md:1257-1273 enforces each mechanically; bin/run_state_lib.validate_phase_artifacts(quality_dir, phase=1) is the programmatic enforcer — your artifact has to pass it before Phase 2 will start). The exact titles are load-bearing — do NOT substitute "equivalent" headings:

1. ## Open Exploration Findings — at least 8 numbered entries (1., 2., ...). Each entry has at least one file:line citation in the body (e.g., bin/foo.py:120-135). At least 3 of these entries trace behavior across 2 or more distinct file:line locations (multi-location traces — the entry cites two or more different file:line ranges).

2. ## Quality Risks — domain-knowledge risk analysis. Numbered or bulleted; cite file:line where risks are concretely visible in code or docs.

3. ## Pattern Applicability Matrix — a Markdown table with one row per exploration pattern from references/exploration_patterns.md. Decision column values are FULL or SKIP. Between 3 and 4 patterns must be marked FULL (inclusive — the gate rejects below 3 because exploration didn't pick enough patterns, and above 4 because exploration ran every pattern instead of selecting). Skipped patterns are still listed with SKIP and a brief reason, so the matrix is exhaustive.

4. ## Pattern Deep Dive — <pattern-name> — at least 3 sections, one per FULL pattern. Each deep dive enumerates concrete findings with file:line citations. At least 2 of these sections trace code paths across 2 or more distinct identifiers (e.g., backtick-quoted function or symbol names like \docs_present`, `_evaluate_documentation_state``) OR across 2 or more distinct file:line locations — that's how the gate detects "multi-function trace" rather than a one-anchor finding.

5. ## Candidate Bugs for Phase 2 — numbered list of bug hypotheses promoted from the deep dives + open exploration. Each entry has a Stage: line attributing the source (e.g., Stage: open exploration, Stage: quality risks, or Stage: <Pattern Name>). At least 2 entries must be sourced from open exploration / quality risks AND at least 1 entry must be sourced from a pattern deep dive. Combo stages (Stage: open exploration + Cross-Implementation Consistency) count toward both buckets.

6. ## Gate Self-Check — proves you ran the Phase 1 gate. List each of the 13 checks (≥120 lines + six required headings + ≥3 Pattern Deep Dive sections + PROGRESS.md mark + ≥8 findings with citations

   • ≥3 multi-location findings + 3-4 FULL pattern matrix rows + ≥2 multi-function deep dives + candidate-bug source mix) and mark whether the artifact satisfies each.

In addition, ensure quality/PROGRESS.md exists and its Phase 1 line is marked [x] (the gate's check 8) before declaring Phase 1 complete.

The exploration content the prior versions of this prompt asked for (domain and stack identification, architecture map, existing test inventory, specification summary, skeleton/dispatch analysis, derived requirements REQ-NNN, derived use cases UC-NN, file-role tagging summary) lives WITHIN these required sections — for example, the architecture map and module enumeration belong under ## Open Exploration Findings as multi-location findings; the file-role tagging summary and the exploration_role_map.json breakdown summary belong under ## Open Exploration Findings or ## Quality Risks as analytical content; derived REQ-NNN and UC-NN sections may appear after ## Gate Self-Check as additional analytical material the playbook downstream phases consume. Do NOT use these alternative names as TOP-level section titles — the gate requires the six exact titles above and the Pattern Deep Dive prefix; additional ## sections beyond these are tolerated for analytical extension but the six gate-required titles MUST appear verbatim.

MANDATORY CARTESIAN UC RULE (Lever 1, v1.5.2)

For every requirement with a References field naming ≥2 files (or ≥2 file:line ranges in distinct files), apply the Cartesian eligibility check before deciding whether to emit a single umbrella UC or per-site UCs:

Gate 1 — Path-suffix match. At least two references must share a path-suffix role: the last segment before the extension, or a matching function-name pattern that appears across the files.

• Example of a match: virtio_mmio.c, virtio_vdpa.c, virtio_pci_modern.c all implement _finalize_features. The _finalize_features function is the shared role.
• Example of a non-match: CONFIG_FOO, CONFIG_BAR flags in the same kconfig file — same kind of thing, but not parallel implementations.

Gate 2 — Function-level similarity. Each matching reference must cite a line range of similar size (within 2× of the median) and each range must be inside a function body — not a file-header, a kconfig block, or a macro expansion list.

Decision:

• Both gates pass → emit one UC per site, numbered UC-N.a, UC-N.b, UC-N.c, … Each per-site UC has its own Actors, Preconditions, Flow, Postconditions. The parent REQ-N remains as the umbrella.
• Only Gate 1 passes → keep a single umbrella UC and mark the reference cluster heterogeneous in a <!-- cluster: heterogeneous --> HTML comment in the UC body. Phase 3 can still override if it finds per-site divergence.
• Neither gate passes → single umbrella UC, no special marking.

Worked example — REQ-010 / VIRTIO_F_RING_RESET (virtio)

Suppose Phase 1 derives:

### REQ-010: Virtio transports must honor VIRTIO_F_RING_RESET negotiation
- References: drivers/virtio/virtio_mmio.c, drivers/virtio/virtio_vdpa.c, drivers/virtio/virtio_pci_modern.c
- Pattern: whitelist

Applying the Cartesian check:

• Gate 1: all three files contain _finalize_features functions — matches.
• Gate 2: each cited range is inside a function body of similar size — matches.

Both gates pass → emit per-site UCs:

### UC-10.a: VIRTIO_F_RING_RESET on PCI modern transport
- Actors: virtio_pci_modern driver, guest kernel
- Preconditions: device advertises VIRTIO_F_RING_RESET
- Flow: vp_modern_finalize_features propagates bit through config space …
- Postconditions: feature_bit reflected in final config

### UC-10.b: VIRTIO_F_RING_RESET on MMIO transport
- Actors: virtio_mmio driver, guest kernel
- Preconditions: device advertises VIRTIO_F_RING_RESET
- Flow: vm_finalize_features must mirror PCI modern behavior …
- Postconditions: feature_bit survives finalize call

### UC-10.c: VIRTIO_F_RING_RESET on vDPA transport
- Actors: virtio_vdpa driver, vdpa device backend
- Preconditions: device advertises VIRTIO_F_RING_RESET
- Flow: virtio_vdpa_finalize_features forwards through set_driver_features …
- Postconditions: feature_bit visible to vdpa backend

CONFIRMATION CHECKLIST (Cartesian UC rule)

Before completing Phase 1, confirm each item explicitly in EXPLORATION.md under a section titled "Cartesian UC rule confirmation":

1. For every REQ with ≥2 References, I ran Gate 1 (path-suffix match).
2. For every REQ that passed Gate 1, I ran Gate 2 (function-level similarity).
3. Where both gates passed, I emitted per-site UCs (UC-N.a, UC-N.b, …).
4. Where only Gate 1 passed, I marked the cluster <!-- cluster: heterogeneous -->.
5. Where neither gate passed, I kept a single umbrella UC without marking.
6. For each REQ with a pattern match in Gate 1, I added Pattern: whitelist|parity|compensation to the REQ block.

Also initialize quality/PROGRESS.md with the run metadata and the phase tracker in the EXACT checkbox format below. This format is a hard contract: the Phase 5 gate checks for the substring - [x] Phase 4 before allowing reconciliation to start, and it only matches the checkbox form. Do NOT substitute a Markdown table, bulleted prose, or any other layout — table-format runs have aborted mid-pipeline because the gate does not see "Complete" in a table cell as equivalent.

Template for the phase tracker section of PROGRESS.md (fill in the Skill version from SKILL.md metadata):

# Quality Playbook Progress

Skill version: <vX.Y.Z>
Date: <YYYY-MM-DD>

## Phase tracker

- [x] Phase 1 - Explore
- [ ] Phase 2 - Generate
- [ ] Phase 3 - Code Review
- [ ] Phase 4 - Spec Audit
- [ ] Phase 5 - Reconciliation
- [ ] Phase 6 - Verify

As each later phase completes it will flip its own - [ ] to - [x] — keep the line text (including the phase name after the dash) stable so substring matching in the Phase 5 gate and downstream tooling works.

IMPORTANT: Do NOT proceed to Phase 2. Your only job is exploration and writing findings to disk. Write thorough, detailed findings - the next phase will read EXPLORATION.md to generate artifacts, so everything important must be captured in that file.