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

!cat skills/parallelize/owns-defers.md

## 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`. <!-- id-hygiene-exempt -->
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 (per the per-task spec contract in `skills/plan/SKILL.md`), 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

!cat skills/_shared/multi-actor-flow-check.md

## Process Steps

**Compaction checkpoint: pre-fanout.** Steps 2–8 below read every current-phase task spec, synthesize the dependency graph + Waves + Branch Map, and render the Mermaid diagram into `parallelization.md`. The synthesis subagent (or inline synthesis) reads many tasks and produces large output. See using-qrspi `## Compaction Checkpoints` for the iron-rule contract.

Surface a todo: title `Recommend /compact (pre-fanout) — parallelize`, description `pre-fanout: dependency-graph synthesis reads every current-phase task spec; large output. User decides whether to /compact.`.

1. Identify current phase's tasks from `plan.md` phase definitions
2. For each task, list dependencies and files-touched (read each `tasks/task-NN.md` or `fixes/{type}-round-NN/*.md`)
3. Group tasks into Waves (independent + file-disjoint share a Wave; otherwise separate Waves)
4. Determine execution mode (sequential / parallel / hybrid) — pick the simplest mode the dependency graph supports
5. For each Wave, decide its symbolic base per the Branch Model. For multi-parent dependencies, name a stage commit (`stage-after-W{N}`); for single prior-Wave parents, name that task's tip; for sequential chains, name the previous task's tip.
6. Build the Wave dependency graph: Wave 1 contains all Waves whose only dependency is the feature branch tip; downstream Waves declare their prerequisite Waves. Implement's runtime rule dispatches every Wave whose dependencies are satisfied each tick — concurrency derives from the dependency graph at runtime, not from Wave numbering.
7. Write `parallelization.md` with the required sections (Dependency Analysis table, Branch Map organized into `### Wave N` sub-sections each with a Task/Branch/Base mini-table, Stage Commits table if any)
8. Render the Mermaid dependency graph into the same file (do not paste the diagram into the terminal — the user opens the file to view it)
9. Present the plan to the user for approval

### Worktree-Aware Setup Validation

Before scheduling parallel task branches, validate that the project's lint/typecheck/test configurations exclude the worktree-tree pattern QRSPI uses. The Implement skill creates per-task worktrees under `.worktrees/<project>/task-NN/`, each of which may contain its own framework build directory (e.g., `.next/` for Next.js, `dist/` for Vite, `build/` for many bundlers). Without explicit exclusions, project-level lint/test invocations walk into sibling worktrees' build outputs, producing thousands of noise findings on minified code.

Validate in this order, on the project root (not in a worktree):

1. **eslint** — config (`eslint.config.js`, `.eslintrc*`, `package.json` `eslintConfig`) ignores `.worktrees/**` AND the framework build directory (`.next/**`, `dist/**`, `build/**`).
2. **tsconfig** — `tsconfig.json` `exclude` array contains `.worktrees/**` (or equivalent). If the project uses path aliases pointed at the project root, also confirm aliases don't accidentally re-include worktree paths.
3. **vitest / jest** — test config's `exclude` (or `testPathIgnorePatterns`) contains `.worktrees/**`.
4. **framework build dir under worktrees** — verify recursive globs (e.g., `.next/**` not just `.next/`) so deep worktree subtrees are covered.

**This validation is advisory, not blocking.** A missing exclusion does not halt parallelization. Surface findings as remediation suggestions in the parallelize artifact (`parallelization.md`) and as a notification line for the human reviewer:

From dfrysinger/qrspi-plus, MIT.

More from dfrysinger/qrspi-plus