parallelize

Files (3)

• SKILL.md
• owns-defers.md
• worked-examples.md · references/

SKILL.md (first lines)

# Parallelize (QRSPI Step 8)

**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 Parallelize skill to analyze task dependencies and produce a parallelization plan."

## Overview

Plan-time artifact for the current phase. Analyze dependencies and file overlap across `tasks/*.md` (or fix-task batches), determine execution mode (sequential/parallel/hybrid), and write `parallelization.md` containing a Dependency Analysis table, a symbolic Branch Map, and (if needed) a Stage Commits table. Get human approval, then hand off to Implement — which is the runtime owner of branch creation, worktrees, baseline tests, and the per-task orchestration loop.

Parallelize never creates branches, never runs baseline tests, never dispatches per-task subagents. Anything that requires resolving a symbolic base to a real commit happens in Implement.

## Why This Skill Is Separate From Implement

Earlier QRSPI revisions folded planning and runtime into a single Worktree skill. This created a half-static / half-runtime artifact: the Branch Map's `Base` column referenced stage commits that did not exist at plan time, so the document changed meaning between approval and execution. Splitting Parallelize (plan-time, symbolic) from Implement (runtime, concrete) restores QRSPI's "one skill = one artifact + one human gate" symmetry. Parallelize owns `parallelization.md` and the parallelization-plan gate; Implement owns the per-task orchestration loop and the batch gate.

## Iron Law

```
NO TASK DISPATCH WITHOUT AN APPROVED PARALLELIZATION PLAN
```

Parallelize is the skill that produces and gates the plan; Implement is the skill that consumes and enforces it.

## Parallelize OWNS / Parallelize DEFERS

This is the locked rule set the scope-reviewer dispatch consumes (Read by the `qrspi-parallelize-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.

### Parallelize OWNS

- The dependency graph between current-phase tasks (logical task-to-task dependencies recorded in the Dependency Analysis table).
- File-overlap analysis across tasks (the file-disjointness check that distinguishes Waves from collisions inside a Wave).
- Wave membership and Wave bases, the Wave dependency graph, the symbolic Branch Map, and the Stage Commits table when multi-parent dependencies require stage commits.
- The Mermaid dependency graph rendered into `parallelization.md`.
- The Execution Mode decision (sequential / parallel / hybrid) with one-sentence rationale.
- **Worktree-Aware Setup Validation (advisory surface only):** Parallelize surfaces remediation guidance when task file paths, branch-naming patterns, or worktree conventions indicate a setup prerequisite that Implement must satisfy before the first Wave can begin. Parallelize documents the finding in `parallelization.md` so Implement can act on it. Parallelize does NOT auto-patch `parallelization.md` or perform the setup itself — actual worktree creation, branch creation, baseline-test execution, and on-disk config edits remain with Implement (see DEFERS below).

### Parallelize DEFERS

- Task specs themselves (acceptance tests, dependencies-list, LOC estimate, description) — owned by Plan (`plan.md` + `tasks/*.md`). Parallelize consumes these as inputs and MUST NOT rewrite them.
- Per-task implementation logic (how a task achieves its goal; the actual code, test assertions, file edits) — owned by Implement (per-task TDD + review flow — see `implement/SKILL.md` § Per-Task Execution).
- Architecture decisions and trade-offs (which approach the project takes; why a slice exists) — owned by Design.
- Phasing decisions, vertical slices, Iron Law 1 rationale, the Phase 1 PoC guideline, roadmap maintenance — owned by Phasing.
- Concrete commit hashes, branch creation, worktree creation, baseline tests, runtime-injected `task-00` — owned by Implement at runtime; Parallelize records only symbolic bases.
- `review_depth` / `review_mode` / other runtime-only review configuration — owned by Implement (written into `config.md` at phase start).
- Worktree creation, branch creation, baseline-test execution, and on-disk `config.md` edits — owned by Implement even when Parallelize surfaces a Worktree-Aware Setup Validation finding. Parallelize's responsibility ends at surfacing the remediation guidance; Implement performs the work.

## Artifact Gating

Required inputs:

- `plan.md` with `status: approved`
- `tasks/*.md` (current phase) or `fixes/{type}-round-NN/*.md` (for fix-task routing)
- `phasing.md` with `status: approved` (phase definitions and slice ownership)
- `config.md`

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`. Parallelize validates `pipeline`, `route`, and (when `pipeline: quick`) `question_budget`.

<HARD-GATE>
Do NOT mark `parallelization.md` approved while Waves overlap on files.
Do NOT include forward-only dependencies (task-N depending on task-M where M > N within a sequential chain) in the Dependency Analysis.
Do NOT name a Base in the Branch Map that the Branch Model does not authorize (see Branch Model below).
This applies regardless of how simple the phase appears.
</HARD-GATE>

## Execution Modes

| Mode | When | Branch Map shape |
|------|------|------------------|
| Sequential | Tasks form a chain (A→B→C) | Each task's base is the previous task's tip |
| Parallel | Tasks are independent and file-disjoint | Every task in the Wave shares the Wave's base |
| Hybrid | Mix of independent and dependent tasks | Waves share a base; downstream Waves fork from a stage commit, a single prior tip, or `task-00` per the Branch Model |

## Branch Model (Symbolic — Resolved by Implement)

`parallelization.md` records every task's `Base` as a **symbolic** reference. Implement resolves each symbolic reference to a concrete commit at runtime — including creating stage commits when needed.

1. **Feature branch:** `qrspi/{slug}/main` (e.g., `qrspi/user-auth/main`). Created by Implement from the current branch (typically `main`) at the start of the first phase. For subsequent phases, the feature branch already exists.

   **Why `/main`, not bare `qrspi/{slug}`** (F-14): git stores refs hierarchically and cannot have both a leaf ref `qrspi/{slug}` and a namespace `qrspi/{slug}/...` simultaneously. Naming the feature branch `qrspi/{slug}/main` makes it a sibling of the task branches under the `qrspi/{slug}/` namespace — all four kinds of branches (feature `main`, `task-NN`, `task-NNa`, `stage-after-W{N}`) coexist as namespace siblings. Bare `qrspi/{slug}` would deadlock the very first task-branch creation with `fatal: cannot lock ref ... 'refs/heads/qrspi/{slug}' exists`.
2. **Task branches — base depends on execution mode:**
   - **Wave:** A set of tasks that share a base AND have no file overlap. Wave numbering does not imply dispatch ordering — Implement's runtime rule is "dispatch every Wave whose dependencies are satisfied each tick."
   - **Parallel:** Every task in the Wave shares the Wave's *base tip* (see Hybrid below for Waves beyond Wave 1; Wave 1's base is the feature branch tip). Tasks in a Wave are independent by construction (no file overlap, no logical dependency).
   - **Sequential chain:** Task-N's base is task-(N-1)'s tip — *not* the feature branch. This is required because sequential dependencies mean task-N imports types/factories/actions/migrations introduced by task-(N-1), and the feature branch does not yet contain task-(N-1)'s work (Integrate runs once at phase end, not per-task).
   - **Hybrid (multi-parent):** When a downstream task or Wave depends on more than one task from a prior Wave, the symbolic base is `stage-after-W{N}`. Implement creates the intermediate stage commit `qrspi/{slug}/stage-after-W{N}` by merging the prior Wave's tips into a temporary branch; the next Wave then forks from that commit. Stage branches are scratch infrastructure created by Implement; their lifecycle end (merge semantics + cleanup) is Integrate's concern — see `integrate/SKILL.md` → `Merge Strategy`.
   - **Single-parent across Waves:** When a downstream task depends on exactly one task from a prior Wave, name that task's tip directly as the base — no stage commit needed.
   - **Baseline fix (`task-00`) interaction:** When Implement's baseline tests fail and the user chooses Auto-fix (see `implement/SKILL.md` → "Baseline Tests"), `task-00` is injected as a phase-level predecessor. `task-00`'s base is the feature branch tip; every other task in the phase then takes `task-00`'s tip as its base (or as one of its parents in the multi-parent case). This injection happens at runtime — Parallelize does not anticipate it. Implement persists the injection by appending a `task-00` row to the Branch Map *and* writing a `## Runtime Adjustments` section to `parallelization.md` that lists every task whose effective base changed; the original Branch Map rows are not rewritten. Readers (human or agent) reconstruct effective bases by reading the Branch Map and overlaying `## Runtime Adjustments`.
   - **Re-fork semantics (re-run, fix-round, replan):** Once a task branch exists, it is canonical for that task. Implementer-fix-round dispatches reuse the existing branch and add commits. Re-forking only happens at fresh worktree creation: a new task in a new phase, a replan-introduced task, or an explicit user-requested reset. Never re-fork an existing task branch silently — downstream task branches that descend from it would be invalidated.
   - **Reference-gate wave termination:** When a task carries `reference_gate: true` in its frontmatter (introduced by T24's per-task spec contract), it acts as a **wave-terminating task** — it ends its Wave, and no dependent task in any later Wave may dispatch until the reference-gated task clears. Concretely: (1) the reference-gated task occupies its own Wave (it cannot share a Wave with independent tasks, since independent tasks might otherwise dispatch in the same slot); (2) every task that depends on the reference-gated task lands in the next Wave at the earliest; (3) `parallelization.md` emits an explicit note for each reference-gated task (canonical shape: `Reference gate: task-NN ({task name}) — dependents waiting: task-XX, task-YY, task-ZZ`). If a plan contains a reference-gated task, Parallelize applies this rule automatically — it is not an operator override. A reference-gated task that has no dependents still terminates its Wave (it may not run in parallel with other tasks in its Wave), but the "dependents waiting" list is empty.

   - **Symbolic base vocabulary** (the only values allowed in the `Base` column):
     - `feature branch tip` — the tip of `qrspi/{slug}/main` at runtime
     - `task-NN tip` — the tip of `qrspi/{slug}/task-NN` (for single-parent forks across Waves, or sequential-chain predecessors)
     - `stage-after-W{N}` — the stage commit Implement creates by merging Wave N's leaves before forking the next Wave (single stage per Wave)
     - `stage-after-W{N}{suffix}` — when a Wave emits multiple stage commits (e.g., partial-merge checkpoints before different downstream Waves), each stage is distinguished by a single lowercase letter suffix: `a`, `b`, `c`, … The suffix alphabet is ordered (`a` first, then `b`, etc.) and scoped to the originating Wave index `{N}`. For example, Wave 2 with two downstream dependency groups produces `stage-after-W2a` and `stage-after-W2b`. The unsuffixed form `stage-after-W{N}` is the canonical choice when a Wave produces only one stage commit; the suffix is added only when multiple stages from the same Wave are required.
     - `task-00 tip` — the tip of the baseline-fix branch (only after Implement injects `task-00`)
   - Branch naming (informational — Implement creates the branches): `qrspi/{slug}/task-NN`; stage branches `qrspi/{slug}/stage-after-W{N}` and, when multiple stages per Wave are needed, `qrspi/{slug}/stage-after-W{N}{suffix}` (e.g., `qrspi/{slug}/stage-after-W2a`, `qrspi/{slug}/stage-after-W2b`).
3. **Merge target:** Integrate merges all task branches into the feature branch **once at phase end**, not per-task. The feature branch only changes via Integrate. (See `integrate/SKILL.md` → "Merge Strategy" for how Integrate handles dependency-ordered merges and stage-commit dedup.)
4. **PR target:** Test creates the PR from the feature branch to the base branch.

> **Why the base-naming rule matters.** A common misread is *"all task branches always fork from the feature branch."* That works for parallel-only phases but breaks sequential dependencies — task-N's worktree would start without task-(N-1)'s code. The correct rule is base-from-feature-tip for Wave 1 parallel members, base-from-previous-tip for sequential-chain members, base-from-stage-commit when a Wave has multi-parent dependencies, base-from-task-NN-tip when a downstream task has a single prior-Wave parent, and base-from-task-00-tip after a baseline fix is injected. Parallelize records the symbolic name; Implement resolves it to a concrete commit and creates stage commits as needed.

## Multi-Actor Flow Check

## Multi-Actor Flow Check

Before authoring any deliverable that operationalizes a design decision involving two or more actors — where "actor" means anything that performs an operation and hands off to another: scripts, subagents, orchestrators, tools, services, protocol participants, object-call participants, workflow steps, queue producers/consumers, function callers/callees — verify that the design specifies all six choreography elements:

1. **Actor inventory** — every participant named, with its role.
2. **Sequence of operations** — ordered list of who-does-what; parallelism boundaries explicit.
3. **Per-step inputs and outputs** — what each actor receives and produces at each step; where outputs are written (stdout, file path, return value, manifest entry, message).
4. **Consumer identification** — for every output, who reads it next. Outputs with no named consumer must be removed or the consumer surfaced.
5. **Loud-failure paths** — what happens when each step fails; where the failure surfaces; which actor catches it. Silent fallback is never the answer.
6. **Context-cost call-out** — for any flow that crosses a context boundary (orchestrator/subagent, process, network), explicitly state what crosses vs. what stays on disk or in the other context.

From dfrysinger/qrspi-plus, MIT.

More from dfrysinger/qrspi-plus