pi-gauntlet 4.13.1 → 5.0.0

package/skills/subagent-driven-development/SKILL.md

@@ -53,11 +53,11 @@ Before the first task, enter the implement phase: `phase_tracker({ action: "star
 
 For each task in `plan_tracker`:
 
-1. **Dispatch implementer.** Pass the full task text + scene-setting context. Don't make the subagent re-read the plan.
+1. **Dispatch implementer.** Pass the full task text + scene-setting context + the task's plan-declared test commands as `SCOPED_TEST_COMMANDS` (or `none`). Don't make the subagent re-read the plan.
 2. **Handle implementer status** (see below).
 3. **Dispatch spec reviewer.** Verify the diff matches the spec — nothing missing, nothing extra.
 4. If spec reviewer finds gaps → re-dispatch implementer to fix → re-review. Loop until ✅, within [Fix-Loop Rounds](#fix-loop-rounds).
-5. **Dispatch code-quality reviewer.** Only after spec is ✅. Skip for doc-only tasks (every file in the task's `Files:` block documentation-only) — SR-only, same exemption as doc-only waves.
+5. **Dispatch code-quality reviewer.** Only after spec is ✅. Skip for doc-only tasks (every file in the task's `Files:` block documentation-only) — SR-only, same exemption as doc-only waves. Pass `SCOPED_TEST_COMMANDS` = the task's plan-declared commands.
 6. If quality reviewer finds issues → re-dispatch implementer → re-review. Loop until ✅, within [Fix-Loop Rounds](#fix-loop-rounds).
 7. Mark task complete in `plan_tracker`.
 
@@ -71,6 +71,8 @@ One rule governs both review loops - spec-compliance and code-quality - in seque
 
 **Fix fan-out.** When the triggering review's `Parallel-safe:` line certifies a `disjoint` group of ≥ 2 findings, dispatch that fix round per `dispatching-parallel-agents` "Fix fan-out"; the fan-out counts as **one** fix against this budget, its scoped test gate is the consuming task/wave's plan-declared commands, and one re-review of the integrated delta follows.
 
+Every fix re-dispatch (implementer) and code-review re-review carries the consuming task/wave's `SCOPED_TEST_COMMANDS`; spec-reviewer re-reviews carry none - SR never executes.
+
 **The sequence.** Each review that finds issues is a decision point: read the `TRAJECTORY:` line before dispatching anything (review 1 has no line - on issues, dispatch fix 1). Any clean review ends the loop.
 
 1. **Review 1** (first review - no sentinel). Issues -> dispatch fix 1.
@@ -128,13 +130,13 @@ When in doubt, default. Don't downgrade reviewers — false negatives are expens
 
 ```ts
 // implementer
-subagent({ agent: "implementer", task: "<task text + context + status protocol>" })
+subagent({ agent: "implementer", task: "<task text + context + SCOPED_TEST_COMMANDS + status protocol>" })
 
 // spec compliance
 subagent({ agent: "spec-reviewer", task: "<diff range + spec excerpt + ask: does this match?>" })
 
 // code quality
-subagent({ agent: "code-reviewer", task: "<diff range + ask: production-ready?>" })
+subagent({ agent: "code-reviewer", task: "<diff range + SCOPED_TEST_COMMANDS (task commands; wave: union; whole-diff: none) + ask: production-ready?>" })
 
 // closing-loop conformance (origin vs deliverable) — its OWN dispatch, never fused with code quality
 // model: call gauntlet_setting({ key: "closureReview" }) first; use the returned model (omit model: if undefined to inherit) and maxFixRounds
@@ -167,10 +169,10 @@ Auto-selected at handoff by `writing-plans` (any wave with ≥2 tasks) when the
 
 1. **Independence check.** Parse the wave's tasks' `Files:` blocks; assert pairwise-disjoint (mechanical). Runtime-resource disjointness (DB/schema, port, fixture, external service, shared temp path) is not machine-checkable here — trust the plan's wave grouping, which `writing-plans`' D5 contract guarantees. Either kind of overlap → the wave is mis-grouped; run those tasks as sequential single-task waves and note it.
 2. **Fan out.** One parallel dispatch (shape below): `implementer` per task, `context: "fresh"`, `worktree: true`. Each returns a status + a patch.
-3. **Status + spec review per task.** Parse each `DONE`/`BLOCKED`/etc. (see [Implementer Status](#implementer-status)) **first**. Then **dispatch a `spec-reviewer` per accepted patch** (`DONE`, or a `DONE_WITH_CONCERNS` you proceeded with) in one parallel fan-out — `context: "fresh"`, `cwd: <this worktree>`, **no `worktree` flag** (read-only) — each passed its task text, the returned **patch diff**, and the absolute spec path. Review is **diff-based**: the diff's hunks carry `file:line`, and test execution is not the reviewer's job here (the wave test gate in step 5 runs the wave's declared test commands). Inline verdicts are fine at normal wave sizes; large waves use `output:` + `outputMode: "file-only"` to keep verdicts out of your context. **Re-dispatch by cause:** `BLOCKED`/`NEEDS_CONTEXT` per the [Implementer Status](#implementer-status) matrix; a **spec gap** re-dispatches the implementer (fresh, `worktree: true`) carrying the prior patch + the reviewer's findings, the new patch superseding the old at step 4. Loop until accepted + spec ✅, within [Fix-Loop Rounds](#fix-loop-rounds), same as sequential.
+3. **Status + spec review per task.** Parse each `DONE`/`BLOCKED`/etc. (see [Implementer Status](#implementer-status)) **first**. Then **dispatch a `spec-reviewer` per accepted patch** (`DONE`, or a `DONE_WITH_CONCERNS` you proceeded with) in one parallel fan-out — `context: "fresh"`, `cwd: <this worktree>`, **no `worktree` flag** (read-only) — each passed its task text, the returned **patch diff**, and the absolute spec path. Review is **diff-based**: the diff's hunks carry `file:line`, and test execution is never the reviewer's job - in either mode (persona rule; the wave test gate in step 5 runs the wave's declared test commands). Inline verdicts are fine at normal wave sizes; large waves use `output:` + `outputMode: "file-only"` to keep verdicts out of your context. **Re-dispatch by cause:** `BLOCKED`/`NEEDS_CONTEXT` per the [Implementer Status](#implementer-status) matrix; a **spec gap** re-dispatches the implementer (fresh, `worktree: true`) carrying the prior patch + the reviewer's findings, the new patch superseding the old at step 4. Loop until accepted + spec ✅, within [Fix-Loop Rounds](#fix-loop-rounds), same as sequential.
 4. **Integrate.** `git apply` each task's patch sequentially onto HEAD. Apply fails = textual conflict → drop that task, finish the rest, re-run the dropped task sequentially on the updated HEAD.
 5. **Test gate.** Run the union of the wave's tasks' declared test commands on the integrated tree — the full verification set is the verify phase's job, run once. Failure = semantic conflict or bug → re-run the offending task sequentially, else fix per [When a Subagent Fails](#when-a-subagent-fails).
-6. **Quality review.** Code-quality review on the integrated wave diff; loop fixes to ✅ within [Fix-Loop Rounds](#fix-loop-rounds), same as sequential. Skip for doc-only waves (SR-only per the commit precondition below).
+6. **Quality review.** CR binds to the wave: exactly one **initial** code-review dispatch per code-touching wave, over the integrated wave diff - never per task within a wave, never batched across waves. Subsequent dispatches within the wave are re-reviews triggered only by findings, per Fix-Loop Rounds. Pass `SCOPED_TEST_COMMANDS` = the union of the wave's tasks' declared commands. Code-quality review on the integrated wave diff; loop fixes to ✅ within [Fix-Loop Rounds](#fix-loop-rounds), same as sequential. Skip for doc-only waves (SR-only per the commit precondition below).
 7. **Commit the wave.** Leaves a clean tree; the next wave's children branch from this commit and so see the integrated work.
 
 **Two-stage review is preserved:** spec review per task (pre-integration, dispatched `spec-reviewer` — not inline), quality review per wave (post-integration). A wave commit requires one spec-review verdict per accepted task, plus one code-review verdict on the integrated diff for waves that touch code. A doc-only wave (every task's `Files:` block documentation-only, per `writing-plans`' Wave Grouping) is SR-only — the CR gate does not apply.
@@ -189,8 +191,8 @@ subagent({
   concurrency: 4,        // default; cap = wave size
   tasks: [
     // do NOT set per-task cwd under worktree:true — it must equal the top-level cwd or the run errors
-    { agent: "implementer", task: "<task text + owned files + status protocol>", output: "wave1-task1.md" },
-    { agent: "implementer", task: "<task text + owned files + status protocol>", output: "wave1-task2.md" },
+    { agent: "implementer", task: "<task text + owned files + SCOPED_TEST_COMMANDS + status protocol>", output: "wave1-task1.md" },
+    { agent: "implementer", task: "<task text + owned files + SCOPED_TEST_COMMANDS + status protocol>", output: "wave1-task2.md" },
   ],
 })
 ```
@@ -215,7 +217,7 @@ For the fan-out + worktree + patch-integration + conflict mechanics, see `dispat
 ## After All Tasks Complete
 
 0. Call `phase_tracker({ action: "start", phase: "verify" })`. (The `implement` phase was started at execution start and auto-completes from `plan_tracker` once all tasks are done; this flow runs its own verify gate instead of `/skill:verification-before-completion`, so it must mark verify itself.)
-1. **Run the whole-diff code review.** Dispatch `/skill:requesting-code-review` against the worktree's full diff vs `main` (already covered in [The Process](#the-process) step "After all tasks"). Address Critical and Moderate findings before handoff. (Consumers wanting an in-flow project-specific audit re-add it as an explicit step in the gauntlet overrides file (see Project overrides), or run `/self-audit` manually.)
+1. **Run the whole-diff code review.** Dispatch `/skill:requesting-code-review` against the worktree's full diff vs `main` (already covered in [The Process](#the-process) step "After all tasks"). Address Critical and Moderate findings before handoff. (Consumers wanting an in-flow project-specific audit re-add it as an explicit step in the gauntlet overrides file (see Project overrides), or run `/self-audit` manually.) Pass `SCOPED_TEST_COMMANDS: none` - the verify phase's full run (step 2) is the orchestrator's.
 2. **Run the full verification set — once.** Read the plan header's `**Verification:**` line and run it: tests + style + format (a single bundling entrypoint, or the listed individual commands). Green output is the fresh evidence verify requires; this is the only full run before conformance — task and wave gates ran scoped commands only. After conformance fix rounds land, re-run the set before re-dispatching the gate.
 3. **Close the loop — conformance check.** The review in step 1 is plan-vs-code (single-step); it inherits any requirement the plan already dropped. Before marking verify complete, dispatch a fresh-context **`conformance-reviewer`** — its **own** dispatch, never fused into the step-1 review — to confront the deliverable (code **and** docs) against the *origin* — the spec **and** the original prompt — per `verification-before-completion/reference/conformance-check.md`. Pass the spec path, the verbatim original prompt, and the full diff. Follow that reference for the partition rule, concern decomposition, and fix-loop mechanics; do not reimplement them here. The fix loop may drive `plan_tracker` to surface fix-wave progress (task naming and lifecycle per conformance-check.md's fix loop / the Fix fan-out Progress rule); it never calls `phase_tracker`. Call `phase_tracker({ action: "complete", phase: "verify" })` only when the reference says the handoff is durably complete: either a current `CONFORMS` result, or a current `## Closure / conformance` inventory whose carried-open concerns all come from valid deferred gaps, including `recommended: fix` gaps carried open because a declared precondition made the fix loop unavailable (`maxFixRounds: 0`, or no eligible named-branch worktree). A started positive-cap fix loop that blocks, fails, or exhausts its rounds with an open `fix` gap is escalation, not completion; on escalation, do not complete verify, stop and report.
 4. Summarize what was implemented (tasks completed, files changed, test counts, code-review verdict). Emit the `## Closure / conformance` block exactly as defined in `verification-before-completion/reference/conformance-check.md`: it must open with the two-line sentinel (`status: CONFORMS (0 open)` or `status: GAPS (N open)`, then `audited-base: <full HEAD SHA>`), then carry the exact durable concern schema by reference with no renamed or reformatted fields. `finishing-a-development-branch` Step 3.5 consumes that block verbatim.
@@ -238,6 +240,8 @@ For the fan-out + worktree + patch-integration + conflict mechanics, see `dispat
 - Starting on main without explicit user consent
 - Dispatching `code-reviewer` before every one of the wave's spec-review verdicts has landed (including fusing SR+CR into one parallel call)
 - Dispatching fixes sequentially on a clean HEAD despite a ≥ 2-ID `disjoint` group in the review's `Parallel-safe:` line
+- Dispatching `code-reviewer` per task inside a wave (CR binds to the integrated wave diff)
+- Dispatching an implementer or code-reviewer without a `SCOPED_TEST_COMMANDS` value (commands or `none`)
 - About to run the full verification entrypoint during the implement phase — task and wave gates run scoped, plan-declared commands only; the full set belongs to verify
 
 ## Integration

package/skills/subagent-driven-development/code-quality-reviewer-prompt.md

@@ -14,6 +14,7 @@ Dispatch a subagent with the code-reviewer template:
   PLAN_OR_REQUIREMENTS: Task N from [plan-file]
   BASE_SHA: [commit before task]
   HEAD_SHA: [current commit]
+  SCOPED_TEST_COMMANDS: [the consuming task's plan-declared commands; wave reviews: the union of the wave's tasks' declared commands; `none` for the whole-diff verify-phase review]
 ```
 
 **In addition to standard code quality concerns, the reviewer should check:**

package/skills/subagent-driven-development/implementer-prompt.md

@@ -31,13 +31,19 @@ Dispatch a subagent with this prompt:
     Once you're clear on requirements:
     1. Implement exactly what the task specifies
     2. Write tests (following TDD — failing test first for production code)
-    3. Verify implementation works
+    3. Verify with the commands under SCOPED_TEST_COMMANDS (if `none`, state that)
     4. Commit your work
     5. Self-review (see below)
     6. Report back
 
     Work from: [directory]
 
+    SCOPED_TEST_COMMANDS: [the task's plan-declared test commands, verbatim | none]
+
+    Run ONLY these commands for verification. Never run a repo-wide suite,
+    linter, or type-checker. If the value is `none`, run nothing and say so
+    in your report.
+
     **While you work:** If you encounter something unexpected or unclear, **ask questions**.
     It's always OK to pause and clarify. Don't guess or make assumptions.
 

package/skills/subagent-driven-development/spec-reviewer-prompt.md

@@ -38,6 +38,8 @@ Dispatch a subagent with this prompt:
 
     - **Read code and compare to spec: yes**
     - **Edit, create, or delete any files: NO**
+    - **Run tests, linters, or type-checkers: NO.** Never run tests, linters, or type-checkers. Your evidence is the diff and the files you read.
+    - **Code-quality opinions (naming, design, complexity, test aesthetics, style): NO.** Those belong to code-reviewer. Report only spec-vs-implementation deltas.
     - You are a reviewer. Your output is a written report listing what matches and what doesn't.
     - If you find issues, describe them — do NOT fix them.
 

package/skills/test-driven-development/SKILL.md

@@ -117,11 +117,11 @@ Don't add features, refactor other code, or "improve" beyond what the test requi
 
 Run the test. Confirm:
 - New test passes
-- All other tests still pass
+- The task's scoped commands pass (full-suite verification belongs to the verify phase)
 - Output is pristine (no errors, no warnings)
 
 **Test fails?** Fix code, not test.
-**Other tests fail?** Fix now — don't move on with broken tests.
+**Scoped commands fail?** Fix now — don't move on with broken tests.
 
 ### REFACTOR — Clean Up
 
@@ -176,7 +176,7 @@ Before marking work complete:
 - [ ] Watched each test fail before implementing
 - [ ] Each test failed for expected reason (feature missing, not typo)
 - [ ] Wrote minimal code to pass each test
-- [ ] All tests pass
+- [ ] The task's scoped commands pass (full suite belongs to the verify phase)
 - [ ] Output pristine (no errors, warnings)
 - [ ] Tests use real code (mocks only if unavoidable)
 - [ ] Edge cases and errors covered

package/skills/verification-before-completion/reference/conformance-check.md

@@ -76,8 +76,9 @@ Default: **1 requirement source = 1 spec = code covering every requirement.**
 The requirement source is whatever sits at the top of the priority table — a
 ticket if there is one, otherwise the spec + original prompt. No ticket is fine;
 spec + prompt is a first-class source, not a degraded one. "Every requirement" =
-explicit acceptance criteria / spec clauses **+** implicit notes (ticket body,
-comments, or inline in the prompt). Source and solution must end in sync.
+explicit acceptance criteria / spec clauses **+** quotable notes (written
+sentences in the ticket body, comments, or inline in the prompt - quotable
+verbatim, never derived inferences). Source and solution must end in sync.
 
 Multi-spec effort → allowed **only if the spec explicitly says** it covers a
 defined subset and names the deferred requirements. Silent partial coverage = failure.
@@ -152,7 +153,9 @@ Per round:
    group of ≥ 2 gaps (per the report's `Parallel-safe:` line) fixes in one parallel
    dispatch — one `implementer` per gap (fresh context, `worktree: true`, `cwd` =
    the conformance worktree, task = the gap block verbatim with `touched-files` as
-   the ownership boundary); `conflicts` pairs serialize. Gaps outside any ≥ 2-ID
+   the ownership boundary). The dispatch adds `SCOPED_TEST_COMMANDS` to the gap
+   block: the gap-relevant plan-declared commands, or `none` (the round's test
+   gate owns execution). `conflicts` pairs serialize. Gaps outside any ≥ 2-ID
    `disjoint` group run sequentially as before. Then dispatch `spec-reviewer` per
    gap on the gap-block reference contract below. Task lifecycle: mark `in_progress` at
    dispatch; `complete` is deferred until the gap's patch is successfully
@@ -167,7 +170,7 @@ Per round:
    integrated changes. A `BLOCKED`/`NEEDS_CONTEXT` return surfaces to the user.
 4. **Test gate** on the integrated tree, using the project's canonical test
    command. A failure re-enters the failure-handling rules above.
-5. **`code-reviewer` once** on the round's cumulative fix delta (not per gap).
+5. **`code-reviewer` once** on the round's cumulative fix delta (not per gap), with `SCOPED_TEST_COMMANDS` = the round's gap-relevant commands, or `none` (the round's test gate owns execution).
 6. **Re-audit**: re-dispatch `conformance-reviewer` over the fixes **plus** the
    regression guard (any prior-`DELIVERED` requirement whose `evidence` file
    the fix diff touched). Pass the full prior conformance report (every row,
@@ -269,7 +272,9 @@ is an unmet-delivery fact, not
 an external blocker** — never relabel missing implementation evidence as a
 blocker. A malformed structured reviewer gap block — missing its stable `Gn`
 label or any required field (`verdict`, `origin`, `evidence`, `remediation`,
-`touched-files`, `touched-resources`, `recommended`) — triggers a **fresh
+`touched-files`, `touched-resources`, `recommended`) — or, for any non-`UNAUTHORIZED`
+gap (including re-audit blocks), an `origin` lacking a locator or a nonempty
+quoted fragment — triggers a **fresh
 audit**; a complete structured reviewer gap block does not — the orchestrator
 decomposes it or emits the indivisible fallback.
 
@@ -411,7 +416,7 @@ must map each token to its titled concern or gap before asking for input.
 ```text
 G1 - Source-image validation is incomplete
   verdict: PARTIAL
-  origin: <requirement source and clause>
+  origin: <requirement source and clause> - "<quoted clause>"
   evidence: <current file:line or observed state>
   blocker: <specific blocker, or none>
   touched-files: <paths or unknown>
@@ -421,7 +426,7 @@ G1 - Source-image validation is incomplete
   G1/C1 - End-to-end OCR output has not been validated
     unresolved: <plain statement of the concern>
     impact: <why it matters to the current workflow>
-    origin: <requirement source and clause, narrowed from the gap origin; or none (scope creep) for UNAUTHORIZED>
+    origin: <requirement source and clause, narrowed from the gap origin> - "<quoted clause>"; or none (scope creep) for UNAUTHORIZED
     remediation: <concern-scoped remediation action>
     evidence: <concern-specific evidence or blocker>
     touched-files: <concern-scoped paths, narrowed from the gap; or unknown>
@@ -474,7 +479,8 @@ branch integration options.
 ## Checklist
 
 - [ ] Located canonical requirements (spec → prompt → ticket fallback)
-- [ ] Enumerated every requirement: explicit ACs / spec clauses + implicit notes + inline prompt reqs
+- [ ] Enumerated every requirement: explicit ACs / spec clauses + quotable notes + inline prompt reqs (verbatim-quotable only)
+- [ ] Every non-UNAUTHORIZED gap's origin carries locator + verbatim quote
 - [ ] Checked spec ↔ prompt/ticket drift; reconciled any divergence
 - [ ] Each requirement mapped to where it's satisfied (code/doc) + evidence
 - [ ] Multi-spec? Subset declared in spec; deferred ACs noted as out of scope

package/skills/writing-plans/SKILL.md

@@ -128,7 +128,8 @@ If you can't list the files, the spec isn't ready. Send it back to `/skill:brain
 Group tasks into **waves** so the executor can parallelize independent work (see `subagent-driven-development` Parallel-Wave Mode). A wave is a maximal set of tasks that (a) have no ordering dependency on each other, (b) own **pairwise-disjoint files**, and (c) contend on **no shared mutable runtime resource** (same DB/schema, port, fixture file, external service, shared temp path).
 
 - Tasks nest under `## Wave N — <label>` headers; `### Task N` headers sit inside a wave.
-- A wave with one task is legal (runs sequentially). A pure dependency chain yields one task per wave — no parallelism, which is correct.
+- Group independent tasks into the same wave by default. A wave with one task is legal **only with a named-blocker justification**: a body line directly under the `## Wave N — <label>` header, `Solo: <reason>`, where the reason names the blocking task/wave, the contended runtime resource, or `lone remaining task` (reserved for the genuinely final unmatched task; doc-only trailing waves qualify). Category-only justifications ("dependency" with no named task) do not satisfy the rule.
+- A pure dependency chain yields one task per wave — no parallelism, which is correct; each such wave carries its `Solo:` line naming the prior-wave dependency.
 - Each wave after the first states its dependency on prior waves.
 
 **File-ownership contract.** The per-task `**Files:**` block *is* the ownership declaration — no new syntax. Rule: **within a wave, the union of every task's declared paths must be pairwise disjoint.** Globs are allowed for `Modify` when exact paths are unknown, but must not overlap another same-wave task's paths. A task that must touch another's file belongs in a later wave.
@@ -152,6 +153,8 @@ Parallel-safe: Tasks 1–3 own disjoint files (see each task's Files block).
 
 ## Wave 2 — Wire-up
 
+Solo: Task 4 depends on Wave 1 Task 1's API (named-blocker justification).
+
 Depends on Wave 1: Task 4 consumes the API introduced by Task 1.
 
 ### Task 4: ...
@@ -269,6 +272,7 @@ After drafting the plan and before announcing it complete, run three checks your
 - **Placeholder scan.** Grep the doc for `TODO`, `TBD`, `xxx`, `[fill in]`, `<example>`, `etc.`, "probably", "something like". Resolve or convert each into an explicit Open Question.
 - **Type / API consistency.** Function signatures and field names that appear in multiple tasks must match exactly. The plan is its own contract — internal contradictions surface as bugs during execution.
 - **Wave disjointness.** For every multi-task wave, confirm the tasks' `Files:` sets are pairwise disjoint **and** that no two tasks contend on a shared mutable runtime resource (DB/schema, port, fixture, external service, shared temp path). Either kind of overlap = mis-grouped wave; split or re-order before handoff.
+- **Solo-wave justification.** Every single-task wave carries a `Solo:` line naming its specific blocker. A solo wave without one is mis-grouped or under-justified — merge it or justify it before handoff.
 - **Scoped-test coverage.** Every code-touching wave declares at least one scoped test command; only doc-only waves may have none.
 - **Header-only entrypoint.** The full verification entrypoint appears only in the plan header's `**Verification:**` line. Grep the task body for the header's command string — expect zero hits.
 

package/skills/writing-skills/SKILL.md

@@ -40,9 +40,9 @@ reference/            # optional progressive-disclosure files
 <supporting>.md       # prompt templates (dispatch payloads)
 ```
 
-`reference/` is the pi pattern for keeping SKILL.md tight while still shipping deep guidance. See `.pi/skills/test-driven-development/reference/` and `.pi/skills/systematic-debugging/reference/` for working examples.
+`reference/` is the pi pattern for keeping SKILL.md tight while still shipping deep guidance. See `.pi/skills/test-driven-development/reference/` for a working example.
 
-Prompt templates and other dispatch payloads - files filled in and passed wholesale into a subagent `task` - live as siblings of SKILL.md, not under `reference/`. See `requesting-code-review/code-reviewer.md` and the three `subagent-driven-development/*-prompt.md` files. The decision criterion is destination, not format: a file passed wholesale into a subagent's `task` is a sibling; a file read at a decision point for deep guidance, examples, or rationale is `reference/`. Some older skills (`systematic-debugging`, `test-driven-development`) keep deep-guidance `*.md` files flat as siblings, predating the `reference/` convention (obra/superpowers lineage) - that is descriptive history, not a mandate to move them.
+Prompt templates and other dispatch payloads - files filled in and passed wholesale into a subagent `task` - live as siblings of SKILL.md, not under `reference/`. See `requesting-code-review/code-reviewer.md` and the three `subagent-driven-development/*-prompt.md` files. The decision criterion is destination, not format: a file passed wholesale into a subagent's `task` is a sibling; a file read at a decision point for deep guidance, examples, or rationale is `reference/`. Some older skills (`test-driven-development`) keep deep-guidance `*.md` files flat as siblings, predating the `reference/` convention (obra/superpowers lineage) - that is descriptive history, not a mandate to move them.
 
 ### Reference Files Bundled With This Skill
 
@@ -151,7 +151,7 @@ description: Use when implementing any feature or bugfix, before writing impleme
 Use skill name with explicit requirement markers. **Never** force-load with `@` syntax — that burns context before the file is needed.
 
 - ✅ `**REQUIRED SUB-SKILL:** Use /skill:test-driven-development`
-- ✅ `**REQUIRED BACKGROUND:** You MUST understand /skill:systematic-debugging`
+- ✅ `**REQUIRED BACKGROUND:** You MUST understand /skill:verification-before-completion`
 - ✅ `> **Related skills:** Pair with /skill:verification-before-completion`
 - ❌ `@.pi/skills/test-driven-development/SKILL.md`
 

package/skills/systematic-debugging/SKILL.md

@@ -1,151 +0,0 @@
----
-name: systematic-debugging
-description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
----
-
-> **Related skills:** Write a failing test for the bug with `/skill:test-driven-development`. Verify the fix with `/skill:verification-before-completion`.
-
-# Systematic Debugging
-
-## Overview
-
-Random fixes waste time and create new bugs. Quick patches mask underlying issues.
-
-**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
-
-**Violating the letter of this process is violating the spirit of debugging.**
-
-Debug discipline is enforced by this skill, not by runtime hooks. The pi `verify-before-ship` extension only gates ship commands; it does not track investigation patterns. Hold yourself to the process below.
-
-## The Iron Law
-
-```
-NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
-```
-
-If you haven't completed Phase 1, you cannot propose fixes.
-
-## When to Use
-
-Use for ANY technical issue: test failures, bugs, unexpected behavior, performance problems, build failures, integration issues.
-
-**Use this ESPECIALLY when:**
-- Under time pressure (emergencies make guessing tempting)
-- "Just one quick fix" seems obvious
-- You've already tried multiple fixes
-- Previous fix didn't work
-- You don't fully understand the issue
-
-**Don't skip when:**
-- Issue seems simple (simple bugs have root causes too)
-- You're in a hurry (rushing guarantees rework)
-
-## The Four Phases
-
-You MUST complete each phase before proceeding to the next.
-
-### Phase 1: Root Cause Investigation
-
-**BEFORE attempting ANY fix:**
-
-1. **Read Error Messages Carefully** — Don't skip past errors or warnings. Read stack traces completely. Note line numbers, file paths, error codes.
-
-2. **Reproduce Consistently** — Can you trigger it reliably? What are the exact steps? If not reproducible → gather more data, don't guess.
-
-3. **Check Recent Changes** — Git diff, recent commits, new dependencies, config changes, environmental differences.
-
-4. **Gather Evidence in Multi-Component Systems** — For each component boundary: log what enters, what exits, verify config propagation. Run once to see WHERE it breaks, then investigate that component.
-
-   **Example (multi-layer system):**
-   ```bash
-   # Layer 1: Workflow
-   echo "=== Secrets available: ==="
-   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
-
-   # Layer 2: Build script
-   echo "=== Env vars in build script: ==="
-   env | grep IDENTITY || echo "IDENTITY not in environment"
-
-   # Layer 3: Signing
-   echo "=== Keychain state: ==="
-   security list-keychains
-   security find-identity -v
-   ```
-   **This reveals:** Which layer fails (e.g., secrets → workflow ✓, workflow → build ✗)
-
-5. **Trace Data Flow** — Where does the bad value originate? What called this with the bad value? Keep tracing up until you find the source. Fix at source, not at symptom. See `root-cause-tracing.md` for the complete technique.
-
-### Phase 2: Pattern Analysis
-
-1. **Find Working Examples** — Locate similar working code in same codebase.
-2. **Compare Against References** — Read reference implementation COMPLETELY. Don't skim.
-3. **Identify Differences** — List every difference, however small. Don't assume "that can't matter."
-4. **Understand Dependencies** — What components, settings, config, environment does this need?
-
-### Phase 3: Hypothesis and Testing
-
-1. **Form Single Hypothesis** — State clearly: "I think X is the root cause because Y." Be specific, not vague.
-2. **Test Minimally** — Make the SMALLEST possible change. One variable at a time. Don't fix multiple things at once.
-3. **Verify Before Continuing** — Did it work? Yes → Phase 4. No → Form NEW hypothesis. DON'T add more fixes on top.
-4. **When You Don't Know** — Say "I don't understand X." Don't pretend to know. Ask for help. Research more. The escape valve is real: an honest "I'm stuck on X" beats a confident wrong fix every time.
-
-### Phase 4: Implementation
-
-1. **Create Failing Test Case** — Use `/skill:test-driven-development` for writing proper failing tests. MUST have before fixing.
-
-2. **Implement Single Fix** — ONE change at a time. No "while I'm here" improvements. No bundled refactoring.
-
-3. **Verify Fix** — Test passes? No other tests broken? Issue actually resolved?
-
-4. **If Fix Doesn't Work:**
-   - If < 3 attempts: Return to Phase 1, re-analyze with new information
-   - **If ≥ 3 attempts: STOP (see below)**
-
-### When 3+ Fixes Fail: Question Architecture
-
-**This is NOT a failed hypothesis — it's a wrong architecture.**
-
-Pattern indicating architectural problem:
-- Each fix reveals new shared state/coupling in different places
-- Fixes require "massive refactoring" to implement
-- Each fix creates new symptoms elsewhere
-
-**STOP and question fundamentals:**
-- Is this pattern fundamentally sound?
-- Are we sticking with it through sheer inertia?
-- Should we refactor architecture vs. continue fixing symptoms?
-
-**Discuss with your human partner before attempting more fixes.**
-
-## Red Flags and Rationalizations
-
-Read `reference/rationalizations.md` for the full table of excuses and the partner-signal redirections. Short version:
-
-- "Quick fix for now, investigate later" → return to Phase 1.
-- "Just try changing X and see if it works" → return to Phase 1.
-- "It's probably X, let me fix that" → return to Phase 1.
-- "One more fix attempt" after 2+ failures → question architecture, don't fix again.
-- Each fix reveals a new problem in a different place → question architecture.
-
-## When Process Reveals "No Root Cause"
-
-If investigation reveals issue is truly environmental, timing-dependent, or external:
-1. Document what you investigated
-2. Implement appropriate handling (retry, timeout, error message)
-3. Add monitoring/logging for future investigation
-
-**But:** 95% of "no root cause" cases are incomplete investigation.
-
-## Supporting Techniques
-
-These techniques are part of systematic debugging and available in this directory:
-
-- **`root-cause-tracing.md`** — Trace bugs backward through call stack to find original trigger
-- **`defense-in-depth.md`** — Add validation at multiple layers after finding root cause
-- **`condition-based-waiting.md`** — Replace arbitrary timeouts with condition polling
-
-Read directly when needed: `reference/rationalizations.md` and the supporting `*.md` files in this directory.
-
-## Project overrides
-
-If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it. Any sections relevant to this skill — by name match, by topic (routing, verification, worktrees, etc.), or by workflow convention — override or extend the instructions above. Project-local `AGENTS.md` is already in context — check it for project-specific routing tables, service paths, and verification commands.

package/skills/systematic-debugging/condition-based-waiting-example.ts

@@ -1,158 +0,0 @@
-// Complete implementation of condition-based waiting utilities
-// From: Lace test infrastructure improvements (2025-10-03)
-// Context: Fixed 15 flaky tests by replacing arbitrary timeouts
-
-import type { ThreadManager } from "~/threads/thread-manager";
-import type { LaceEvent, LaceEventType } from "~/threads/types";
-
-/**
- * Wait for a specific event type to appear in thread
- *
- * @param threadManager - The thread manager to query
- * @param threadId - Thread to check for events
- * @param eventType - Type of event to wait for
- * @param timeoutMs - Maximum time to wait (default 5000ms)
- * @returns Promise resolving to the first matching event
- *
- * Example:
- *   await waitForEvent(threadManager, agentThreadId, 'TOOL_RESULT');
- */
-export function waitForEvent(
-  threadManager: ThreadManager,
-  threadId: string,
-  eventType: LaceEventType,
-  timeoutMs = 5000,
-): Promise<LaceEvent> {
-  return new Promise((resolve, reject) => {
-    const startTime = Date.now();
-
-    const check = () => {
-      const events = threadManager.getEvents(threadId);
-      const event = events.find((e) => e.type === eventType);
-
-      if (event) {
-        resolve(event);
-      } else if (Date.now() - startTime > timeoutMs) {
-        reject(new Error(`Timeout waiting for ${eventType} event after ${timeoutMs}ms`));
-      } else {
-        setTimeout(check, 10); // Poll every 10ms for efficiency
-      }
-    };
-
-    check();
-  });
-}
-
-/**
- * Wait for a specific number of events of a given type
- *
- * @param threadManager - The thread manager to query
- * @param threadId - Thread to check for events
- * @param eventType - Type of event to wait for
- * @param count - Number of events to wait for
- * @param timeoutMs - Maximum time to wait (default 5000ms)
- * @returns Promise resolving to all matching events once count is reached
- *
- * Example:
- *   // Wait for 2 AGENT_MESSAGE events (initial response + continuation)
- *   await waitForEventCount(threadManager, agentThreadId, 'AGENT_MESSAGE', 2);
- */
-export function waitForEventCount(
-  threadManager: ThreadManager,
-  threadId: string,
-  eventType: LaceEventType,
-  count: number,
-  timeoutMs = 5000,
-): Promise<LaceEvent[]> {
-  return new Promise((resolve, reject) => {
-    const startTime = Date.now();
-
-    const check = () => {
-      const events = threadManager.getEvents(threadId);
-      const matchingEvents = events.filter((e) => e.type === eventType);
-
-      if (matchingEvents.length >= count) {
-        resolve(matchingEvents);
-      } else if (Date.now() - startTime > timeoutMs) {
-        reject(
-          new Error(
-            `Timeout waiting for ${count} ${eventType} events after ${timeoutMs}ms (got ${matchingEvents.length})`,
-          ),
-        );
-      } else {
-        setTimeout(check, 10);
-      }
-    };
-
-    check();
-  });
-}
-
-/**
- * Wait for an event matching a custom predicate
- * Useful when you need to check event data, not just type
- *
- * @param threadManager - The thread manager to query
- * @param threadId - Thread to check for events
- * @param predicate - Function that returns true when event matches
- * @param description - Human-readable description for error messages
- * @param timeoutMs - Maximum time to wait (default 5000ms)
- * @returns Promise resolving to the first matching event
- *
- * Example:
- *   // Wait for TOOL_RESULT with specific ID
- *   await waitForEventMatch(
- *     threadManager,
- *     agentThreadId,
- *     (e) => e.type === 'TOOL_RESULT' && e.data.id === 'call_123',
- *     'TOOL_RESULT with id=call_123'
- *   );
- */
-export function waitForEventMatch(
-  threadManager: ThreadManager,
-  threadId: string,
-  predicate: (event: LaceEvent) => boolean,
-  description: string,
-  timeoutMs = 5000,
-): Promise<LaceEvent> {
-  return new Promise((resolve, reject) => {
-    const startTime = Date.now();
-
-    const check = () => {
-      const events = threadManager.getEvents(threadId);
-      const event = events.find(predicate);
-
-      if (event) {
-        resolve(event);
-      } else if (Date.now() - startTime > timeoutMs) {
-        reject(new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`));
-      } else {
-        setTimeout(check, 10);
-      }
-    };
-
-    check();
-  });
-}
-
-// Usage example from actual debugging session:
-//
-// BEFORE (flaky):
-// ---------------
-// const messagePromise = agent.sendMessage('Execute tools');
-// await new Promise(r => setTimeout(r, 300)); // Hope tools start in 300ms
-// agent.abort();
-// await messagePromise;
-// await new Promise(r => setTimeout(r, 50));  // Hope results arrive in 50ms
-// expect(toolResults.length).toBe(2);         // Fails randomly
-//
-// AFTER (reliable):
-// ----------------
-// const messagePromise = agent.sendMessage('Execute tools');
-// await waitForEventCount(threadManager, threadId, 'TOOL_CALL', 2); // Wait for tools to start
-// agent.abort();
-// await messagePromise;
-// await waitForEventCount(threadManager, threadId, 'TOOL_RESULT', 2); // Wait for results
-// expect(toolResults.length).toBe(2); // Always succeeds
-//
-// Result: 60% pass rate → 100%, 40% faster execution