phasing

Files (3)

• SKILL.md
• owns-defers.md
• visual-fidelity-precondition.md · references/

SKILL.md (first lines)

# Phasing (QRSPI Step 5)

**PRECONDITION:** Invoke `qrspi:using-qrspi` skill to ensure global pipeline rules are in context. (Idempotent on session re-entry. Subagents are exempt — SUBAGENT-STOP in using-qrspi handles that.)

**Announce at start:** "I'm using the QRSPI Phasing skill to author vertical slices, phase boundaries, and the roadmap."

## Overview

Translate the approved architecture into delivery units. Phasing owns vertical-slice authoring (Iron Law 1), phase boundary decisions (Phase 1 PoC guideline), `roadmap.md` authoring, current-phase pruning of the four synthesizing artifacts (goals.md, questions.md, research/summary.md, design.md), future-* artifact maintenance, and goal-ID consistency validation across nine target files. Discussion is conversational; a subagent synthesizes the artifact set per round.

Pipeline position: Goals → Questions → Research → Design → **Phasing** → Structure → Plan → Parallelize → Implement → Integrate → Test → Replan. Quick-fix routes skip Phasing entirely.

## Artifact Gating

**Required inputs:**
- `goals.md` with `status: approved`
- `questions.md` with `status: approved`
- `research/summary.md` with `status: approved`
- `design.md` with `status: approved`
- `config.md` (read to determine whether Codex reviews are enabled — see `### Config Validation` below)

If any required artifact is missing or not approved, refuse to run and tell the user which artifact is needed.

### Config Validation

Apply the **Config Validation Procedure** in `using-qrspi/SKILL.md`. Phasing validates `second_reviewer` (expected `true` or `false`). If `config.md` is missing or `second_reviewer` is missing/invalid, halt and present the field-specific menu from the Procedure — do NOT silently default `second_reviewer` to false.

<HARD-GATE>
Do NOT synthesize phasing.md, roadmap.md, or any future-* artifact without all five required inputs approved.
Do NOT prune goals.md, questions.md, research/summary.md, or design.md until phasing.md is reviewed and approved by the user.
Do NOT proceed to Structure without user approval of the Phasing artifact set.
</HARD-GATE>

## Phasing OWNS / Phasing DEFERS

This is the locked rule set the scope-reviewer dispatch loads at review time (Read by the `qrspi-phasing-scope-reviewer` agent at runtime per its rules-loading procedure). Boundary-drift findings dispatch off the DEFERS list; scope-compliance dispatches off the OWNS list.

### Phasing OWNS

- **Vertical-slice authoring** — enumerate end-to-end demonstrable delivery units in `phasing.md` `## Slices`. **Iron Law 1 applies** (see below).
- **Phase boundaries** — group slices into phases with explicit replan-gate criteria per phase, captured in `phasing.md` `## Phases`. **The Phase 1 PoC guideline applies** (see below).
- **roadmap.md authoring** — canonical phase → slice → goal-ID mapping table. Roadmap is the source of truth for which goals belong to which phase via which slice; downstream skills (Structure, Plan, Replan) read from it.
- **Current-phase pruning of four synthesizing artifacts** — split goals.md, questions.md, research/summary.md, and design.md into current-phase content (kept in place) and deferred content (moved to `future-goals.md`, `future-questions.md`, `future-research-summary.md`, `future-design.md`). Individual `research/q*.md` files are NOT split — they remain as full-corpus reference so the summary's Q-attribution links continue to resolve.
- **Future-* artifact maintenance** — `future-goals.md`, `future-questions.md`, `future-research-summary.md`, `future-design.md` are created and updated each Phasing run; consumed by Replan during between-phase transitions.
- **Goal-ID consistency validation** — every goal ID appearing in any of the nine target files (goals.md, questions.md, research/summary.md, design.md, future-goals.md, future-questions.md, future-research-summary.md, future-design.md, roadmap.md) must trace to the canonical roadmap.md set. Orphan IDs flagged for user review.

### Phasing DEFERS

- **Architecture, key decisions, system diagram, per-goal Acceptance blocks, `## Visual-Fidelity Binding` H2** → owned by Design. Phasing consumes design.md; it does NOT re-litigate architectural choices. Release-level `## Test Architecture` is owned by Structure (not Design or Phasing).
- **File paths, module boundaries, interface contracts, file maps** → owned by Structure. Phasing names slices and phases; it does NOT enumerate files or function signatures.
- **Task specs, LOC estimates, ordered task lists, per-task test expectations** → owned by Plan. Phasing produces the input Plan reads from (slice list + phase grouping); it does NOT write task specs.
- **Dependency graph, Wave decisions, branch maps** → owned by Parallelize.
- **Implementation prose, code, hook syntax, subagent dispatch verbs** → owned by Implement and downstream skills. Skill-implementation jargon is a boundary-drift signal in phasing.md.

## Iron Law 1 — Vertical slices, not horizontal layers

Every slice in `phasing.md` `## Slices` must be **end-to-end demonstrable on its own** (DB + service + API + frontend together, where applicable). Horizontal decomposition ("DB layer first, API layer second, frontend third") defers integration risk and breaks Phase 1 PoC's job of proving the full stack works. If a slice cannot be demonstrated independently, it is not a slice — re-decompose.

- BAD: "DB layer, then API layer, then service layer, then frontend"
- GOOD: "User registration (DB + API + service + frontend), then user profile (DB + API + service + frontend)"

## Phase 1 PoC Guideline — prove the full stack end-to-end when possible

**Phase 1 is the PoC**, and it should prove the full stack works end-to-end across every layer the project touches whenever possible. A backend-only Phase 1 tends to hide cross-layer issues until Phase 2+, where they are more expensive to surface — so the default is to pull at least one full-stack slice forward into Phase 1. Departures are fine when there's a real reason (e.g., the frontend depends on a backend contract that genuinely cannot be stubbed for Phase 1, or the project is single-layer by nature). When Phase 1 does not exercise every layer named in design.md, the discussion should name the reason explicitly so reviewers can confirm it's a deliberate choice rather than horizontal layering by accident.

## Process

**Interactive in main conversation** (Goals/Design-style). The user and Claude discuss slice decomposition, phase boundaries, and the Phase 1 PoC scope. A subagent synthesizes `phasing.md`, `roadmap.md`, and the four pruned + four future-* artifacts per round. Each rejection round launches a new subagent with original inputs + all prior feedback files.

### Interactive Phasing Discussion

1. Read `goals.md`, `questions.md`, `research/summary.md`, `design.md` and present a proposed slice decomposition derived from the Design's vertical slices (if any) plus a proposed Phase 1 PoC scope.
2. Discuss with the user: which slices belong in Phase 1 (should satisfy the Phase 1 PoC guideline when possible; departures need an explicit reason), where the replan checkpoints belong, and what gate criteria each phase carries.
3. Collect amendment items from the user: any new slices introduced here must receive their own goal IDs in roadmap.md (do not bare-number-compress amendment items into existing goals when the goal text doesn't cover them — see Goals "Amendment handling").
4. Once the slice set and phase grouping settle, hand off to the synthesis subagent.

### Phasing Synthesis Subagent

Once the discussion settles, launch a **subagent** to synthesize the artifact set.

**Subagent inputs:**
- `goals.md`
- `questions.md`
- `research/summary.md`
- `design.md`
- A summary of the phasing discussion (proposed slices, phase grouping, Phase 1 PoC justification, replan gates, amendment items)
- Any prior feedback files

**Subagent outputs (single round, all artifacts together — atomic emission):**
- `phasing.md` (draft) — see Outputs section below
- `roadmap.md` — canonical phase → slice → goal-ID mapping table
- Pruned `goals.md` — current-phase entries only
- `future-goals.md` — deferred entries
- Pruned `questions.md` — current-phase entries only
- `future-questions.md` — deferred entries
- Pruned `research/summary.md` — current-phase entries only
- `future-research-summary.md` — deferred entries
- Pruned `design.md` — current-phase entries only
- `future-design.md` — deferred entries

**Atomicity (fail-closed).** The synthesis subagent MUST emit all 10 artifacts (phasing.md + roadmap.md + 4 pruned + 4 future-*) in a single return. Partial returns — any missing file, or any pruned/future-* pair imbalanced — invalidate the round. Reviewers MUST reject any synthesis output that omits any of the ten artifacts.

### Four-Artifact Pruning Procedure

For each of `goals.md`, `questions.md`, `research/summary.md`, `design.md`:

1. Identify entries by goal ID. Entries whose goal ID maps (per `roadmap.md`) to the **current phase** stay in the artifact in place.
2. Entries whose goal ID maps to a **future phase** are moved to the corresponding `future-*.md` (`future-goals.md`, `future-questions.md`, `future-research-summary.md`, `future-design.md`).
3. Existing entries already in the `future-*.md` for goal IDs that have moved into the current phase are pulled forward into the current artifact.
4. **Individual research/q numbered files do NOT split** — each research/q file is kept intact as full-corpus reference and remains in the research directory (the file pattern is research/q*.md), so the summary's Q-attribution links continue to resolve.

**Atomicity (fail-closed).** Pruning produces 8 files (4 pruned + 4 future-*). Any missing file or imbalanced pruned/future-* pair invalidates the round; the synthesis subagent MUST emit all 8 in a single return. Reviewers MUST reject any phasing.md emission not accompanied by the complete 8-file pruning set.

### Review Round

Apply the **Standard Review Loop** from `using-qrspi/SKILL.md`. Two parallel reviewer dispatches per artifact per round (quality + scope). Phasing-specific reviewer instructions:

**Dispatch the round through dispatch-agent's high-level entry.** Run `scripts/dispatch-agent.sh --step phasing --round ${ROUND} --artifact-dir <ABS_ARTIFACT_DIR>` (plus the per-skill `--output-dir`/`--artifact`/`--agents` flags below). High-level mode invokes `scripts/review-prep.sh` to emit `<ABS_ARTIFACT_DIR>/reviews/phasing/round-${ROUND}.diff` and threads `diff_file_path:` into each reviewer prompt; the orchestrator runs no `git diff` Bash redirect of its own. When the artifact directory is not inside a git repository, review-prep skips diff emission and `diff_file_path:` is omitted. When using-qrspi step 12 narrows the base ref, pass `--base-ref "$(cat reviews/phasing/round-$((ROUND-1))-commit.txt)"` so review-prep narrows against the prior round's per-round commit SHA (using-qrspi step 12 owns the SHA-format validation and the `anchor-file-missing:`/`sha-format-invalid:` halt directions before the SHA reaches `git diff`). Scope-tag narrowing (when active) reaches reviewers as `scope_hint:` wrapped between `<<<UNTRUSTED-SCOPE-HINT-START id=scope_hint>>>` / `<<<UNTRUSTED-SCOPE-HINT-END id=scope_hint>>>` markers per the reviewer-protocol Reviewer Dispatch Contract.

From dfrysinger/qrspi-plus, MIT.

More from dfrysinger/qrspi-plus