Immutable. This exact content is served forever at /api/v1/blob/1562914047d6e4da.
---
name: execute-backlog
description: Use when ready to attack the GitHub issue backlog with discipline. Scans open issues, bundles related work into an efficient execution plan, executes the bundle with verification, then closes issues + writes a retrospective that includes self-improvement notes for this skill. Trigger phrases — "execute backlog", "work the backlog", "knock down P1 issues", "ship a bundle", "/execute-backlog".
user-invocable: true
---
# Execute Backlog
**Purpose:** turn the GitHub issue backlog into shipped work using a deterministic loop: SCAN → BUNDLE → PLAN → EXECUTE → VERIFY → UPDATE → RETRO. Each pass closes a coherent bundle of issues, leaves the repo greener than it found it, and writes a retro that improves the skill itself.
**Operating principle (Extreme Ownership):** every issue in the bundle is "owned" by the executing agent for the duration of the pass. No half-finished issues. No "punted" verification. If a bundle can't ship clean, the bundle gets descoped — not the verification.
---
## When to Use
- Backlog has ≥5 open issues with `priority:p1` or higher
- A sprint / release-gate moment: pick the next high-impact bundle
- User says "let's work the backlog", "execute audit-2026-05-21", "knock down the killswitch issues"
- Agentic team handoff: spawn one of these per worker, each owning a label-scoped bundle
**Don't use for:**
- One-off bug fixes (use `agent-tdd` directly)
- Backlog audit / re-prioritization (use `architecture-audit`)
- New feature work (use `reactive-feature-dev`)
---
## Inputs (declared by caller)
The skill MUST be invoked with at least one filter — never run unfiltered.
```yaml
filter:
labels: # optional: ["area:providers", "audit-2026-05-21"]
priority: # optional: "p0" | "p1" | "p2"
phase: # optional: "phase:C" | "phase:E"
max_bundle_size: 5 # default 5; cap on issues per execution pass
budget_minutes: 90 # default 90; abort if exceeded, descope cleanly
```
Caller examples:
- `/execute-backlog labels=audit-2026-05-21 priority=p1`
- `/execute-backlog labels=area:providers,phase:E`
- `/execute-backlog labels=health-sweep,priority:p1 max_bundle_size=3`
---
## Phase 1 — SCAN
Query GitHub for candidate issues matching the filter.
```bash
gh issue list \
--state open \
--label "<comma-joined labels>" \
--json number,title,labels,body,createdAt,updatedAt \
--limit 100
```
For each candidate, parse:
- Issue number, title
- All labels (especially `area:*`, `priority:*`, `verified`)
- Primary file/location (regex from body: `**Location:**` line)
- Verified-by present? (boolean — `**Verified-by:**` block in body)
**Filter rules:**
1. Drop any issue without `verified-by:` evidence — file a comment asking for verification; do not execute on unverified claims (the 2026-05-21 inflation pattern is the reason this rule exists)
2. Drop `phase:` mismatches if `phase:` filter was provided
3. Drop issues with the `blocked` label
4. Drop issues assigned to someone else
**Drift check (added 2026-05-21):** for any candidate carrying a verified-by command with file:line references, re-run the command. If the emitted line numbers differ from the issue body's claimed lines by **>5** on any row, mark the candidate `🟡 drift detected` and re-read the cited spans to confirm the semantic cast/pattern still matches. Counts can match while locations move 25+ lines — that means the surrounding logic refactored and the fix shape may no longer apply. Acceptable to proceed; not acceptable to skip the check.
**Drift check addendum (added 2026-05-21 v3): semantic-equivalent pattern grep.** When the issue body claims N sites but the primary grep returns fewer, the gap may be a *syntactic variant of the same anti-pattern*, not real drift. Before declaring `🟡 drift detected`, additionally grep the known equivalence classes:
| Primary pattern | Semantic equivalents to also grep |
|-----------------|-----------------------------------|
| `(x as any)` | `(x as unknown as {…})`, `(x as unknown as Record<…>)` |
| `: any` | `: unknown` (intentional widening), `: Record<string, any>`, untyped function-type `Function` |
| `as Function` | `(...args: any[]) => any`, `Callable` aliases |
If the **sum** of equivalence-class matches reproduces the claimed count, proceed (no drift — issue author counted across both forms). If the sum still falls short, mark drift and re-read the cited spans. (Reason: 2026-05-21 #71 spawn — issue claimed 7 sites; primary grep `(state as any)` returned 3; the other 4 lived under `as unknown as { … }` narrowings. Including both forms recovered the exact 7.)
Output: candidate set, sorted by `priority:p0` > `p1` > `p2` > `p3`, then by `verified` label (verified issues rank higher), then drift-clean before drift-detected.
**Cross-package consistency probe (added 2026-05-22 v9).** When the issue touches per-framework / per-platform packages providing equivalent APIs (e.g., `@reactive-agents/react` + `@reactive-agents/svelte` + `@reactive-agents/vue` all exporting `useAgentStream`-style hooks/factories), briefly diff the impl shape across siblings:
```bash
# Side-by-side compare of equivalent files
diff packages/<sibling-a>/src/<file>.ts packages/<sibling-b>/src/<file>.ts | head -40
```
Same name + equivalent signature + **divergent behavior** = latent defect. Surface in the plan's "Adjacent improvement found" section. Fix opportunistically per the test+fix combo rule (Phase 4 v9). (Reason: 2026-05-22 #82 closeout — vue's `useAgentStream.StreamError` branch threw + was caught by inner try/catch; svelte's equivalent branch used direct `next.error = …; next.status = "error"` and worked correctly. Sibling diff would have flagged the divergence before the test had to.)
---
## Phase 2 — BUNDLE
Group candidates into one **bundle** (max `max_bundle_size`) that ships together. A bundle is *coherent* when ≥1 of these holds:
| Cohesion signal | Example |
|-----------------|---------|
| Same `area:*` label across all members | All `area:providers` |
| Primary files overlap (same dir, same package) | All under `packages/runtime/src/builder/` |
| Root-cause cluster | HS-06/07/08 all share "untyped state shape" |
| Cross-cutting fix shape | "Remove `as any` from N hook surfaces" |
| Untyped schema field needs structured access in callers | Local widening type + boundary helper inside the consuming package — see "default fix shape" below |
**Default fix shape for typing issues (added 2026-05-21 v5).** When the cited `as any` casts all narrow the same schema-typed-`unknown` field, default to:
1. Create `<domain>-context.ts` (or `-state.ts`) in the consuming dir.
2. Define `<Domain>Context = ExecutionContext & { <field>: <ConcreteShape> }` (interface mirroring runtime usage, NOT the schema source-of-truth).
3. Export `as<Domain>Context(c)` boundary helper — single named cast.
4. Migrate each cited site through the helper; delete the cast at sources where the field was already typed (dead-cast sweep — see Phase 4).
Three shipped precedents to copy from: #71 `HandlerState` (`packages/reactive-intelligence/src/controller/handler-state.ts`), #72 typed `BuilderState` option groups (`packages/runtime/src/builder/to-config.ts`), #73 `ThinkContext` (`packages/runtime/src/engine/phases/agent-loop/think-context.ts`). The pattern keeps each fix inside its consuming package (cross-package descope gate satisfied automatically).
**Bundling algorithm:**
1. Take the highest-priority candidate as seed
2. Greedily add candidates that share ≥1 cohesion signal with the bundle
3. Stop at `max_bundle_size` OR when no remaining candidate has cohesion ≥1 with the bundle
4. If the bundle has <2 issues after greedy growth → still proceed (singleton bundles are fine)
**Hard gate (added 2026-05-21): cross-package descope.** Before locking the bundle, re-grep each candidate's verified-by command and inspect the file paths it emits. If those paths span **≥2 packages** (`packages/<a>/…` vs `packages/<b>/…`), descope to a per-package bundle even if the issue body's "Fix direction" suggests otherwise. The body lies; the grep doesn't. (Reason: 2026-05-21 #73 spawn — body said "type properly in the think phase" but the actual `as any` targets resolved to types owned by `@reactive-agents/llm-service` and the kernel-context shape, both other packages.)
**Multi-package test-infra split (added 2026-05-22 v7).** The cross-package gate isn't only for typing/refactor issues — it applies the same way when an issue cites adding tests / infra / docs to N packages. Ship N bundles (one per package), each with its own PR. Name the follow-up bundles in the seed bundle's PR description so the queue is explicit. (Reason: 2026-05-22 #82 spawn — issue cited zero tests across `packages/react/`, `packages/svelte/`, `packages/vue/`. Shipped `bundle/react-smoke-tests` first; named `bundle/svelte-smoke-tests` and `bundle/vue-smoke-tests` as follow-ups in the PR body. Disjoint scopes, independent CI, no cross-package merge conflicts.)
**Output:** named bundle. Pattern: `<area>-<theme>` (e.g., `providers-untyped-hooks`, `runtime-builder-as-any-sweep`).
Open a new GH issue or use an existing tracker as the *bundle parent* — link it to all members via `Tracks: #N` lines. Apply the `tracking` label.
---
## Phase 3 — PLAN
For the bundle, write a concrete execution plan to `wiki/Planning/Implementation-Plans/YYYY-MM-DD-<bundle-name>.md`.
**Plan must contain:**
```markdown
# Bundle: <name>
Date: YYYY-MM-DD
Budget: <budget_minutes> min
Issues: #N, #N, #N
## Acceptance criteria (per issue)
- #N: <one-sentence done definition tied to the verified-by claim>
## Execution units (ordered)
1. **Unit 1:** <one or two issues, ≤45 min, files touched, tests touched>
2. **Unit 2:** ...
## Risk register
- <risk> → <mitigation>
## Verification protocol (cross-cutting)
- `bun test packages/<changed>/` — full pass
- `bun run build` — green
- `bunx turbo run typecheck --filter=<changed>` — green
- Sample replay or trace test if behavior change
## Out-of-scope (explicit)
- <thing> — punt to next bundle
```
**Plan gates:**
- If total estimated effort > `budget_minutes` → descope to fit; do NOT skip verification
- If any unit depends on infra not in the repo → mark `blocked` on that issue, drop from bundle
- If two units conflict (same file, conflicting changes) → sequence them, never parallelize
**Substrate-aware test strategy (added 2026-05-22 v8).** When the bundle adds tests to a new framework/package, identify the test substrate up front. Three classes:
| Substrate | Examples | Default coverage |
|-----------|----------|------------------|
| **Render-bound** | React hooks, Vue `setup()`, web components | Public-surface smoke + type contracts. Behavioral via render = follow-up bundle (justify the `@testing-library/X` + happy-dom investment separately). |
| **Framework-agnostic** | Svelte stores (`writable`), Solid signals, Effect.Effect | Behavioral coverage with mocked I/O (e.g., `globalThis.fetch = async () => new Response(...)`). No DOM/render needed. |
| **Pure** | Plain JS factories, helpers, parsers | Behavioral coverage directly. No mocking infrastructure beyond stub inputs. |
Picking the wrong default = scope creep (render-bound bundle pulled into the test-infra rabbit hole) or coverage gap (framework-agnostic bundle capped at smoke when behavioral was cheap). (Reason: 2026-05-22 #82 spawn — react bundle (#100) capped at 6 smoke cases due to render-context requirement; svelte bundle (#101) shipped 13 cases including 9 behavioral because stores work in any runtime. Coverage gap would have been ~half if both bundles defaulted to "smoke only".)
When in doubt, write one case at the framework-agnostic tier and see if it runs under bare `bun:test`. If yes, proceed behavioral. If "Invalid hook call" / setup errors → drop to smoke + name the follow-up bundle.
Read the `superpowers:writing-plans` skill conventions (location override: `wiki/Planning/Implementation-Plans/`).
**Fire-site reachability check (added 2026-05-21 v4):** before designing integration-style tests for any unit, grep the call graph to verify the test scenario will actually exercise the code under fix. A hook/handler/wrapper can be **registered** without being **fired** if the test scenario routes through an alternate code path (e.g., `withTestScenario` short-circuits the reactive loop and bypasses `runner.ts:683` `runPhaseHooks`). Quick check:
```bash
# 1. Locate where the unit under fix gets invoked
grep -rn "<wrapper-or-helper-name>\|<registered-fn-pattern>" packages/
# 2. Confirm at least one fire site is reached by the planned test config
# (provider, reasoning, strategy, test scenario, etc.)
```
If reachability is uncertain, **default to direct-invocation tests** (instantiate the helper / pull from registry / call wrapper directly) rather than full-stack `agent.run()` tests. Reason: 2026-05-21 #74 spawn — initial test design called `agent.run()` with `withTestScenario` + `withReasoning()`, expecting the harness `before('think')` wrapper to fire. It never did. Probes confirmed the wrapper was registered but the kernel-loop fire site was bypassed. Direct invocation via `RegistrationHarness._collected` pinned the unit in 6 tests, 0 flakes.
**Adjacent-improvement detection at baseline (added 2026-05-25 v11).** When the post-branch baseline `bun test` or `bunx turbo run typecheck` reports failures in the SAME package as the bundle, scan each failure's fix-shape against the bundle's root-cause class:
| Baseline failure type | Adjacent-improvement test |
|------------------------|---------------------------|
| Typecheck red w/ identical anti-pattern as cited verified-by | Add to bundle. Same helper / fix shape. No scope creep. |
| Pre-existing test fail in untouched code path | File follow-up issue; don't block bundle. |
| Lint warning in adjacent file with shared fix recipe | Add to bundle iff ≤5 LOC delta and same package. |
If adjacent improvement adopted, **update the plan doc's "Adjacent improvement found" section** AND broaden the verified-by recheck command from per-file to workspace-wide (or per-package-wide). Generalization of the v9 "test+fix combo" rule. (Reason: 2026-05-25 #85 spawn — baseline typecheck flagged 5 errors in `tests/controller/dispatcher-compose-bridge.test.ts` with identical `InterventionHandler<TDecision>` contravariance root cause as the cited 9 sites in `handlers/index.ts`. Bundling them added 9 helper applications, 0 LOC of new design, silenced all 5 errors. Excluding them would have left a follow-up bundle with one-line diff each — wasteful.)
---
## Phase 3.5 — BRANCH (mandatory)
Before any code edits land, create a dedicated feature branch off `main` for the bundle.
**Local-main-ahead check (added 2026-08-16 v13).** Some repos hold work on local `main` unpushed until a release/tag event (e.g. `reactive-agents-ts` itself — see `.agents/MEMORY.md`'s repo-workflow note). Branching from `origin/main` in that case silently drops every local-only commit from the new branch's base. Check first:
```bash
git fetch origin main
git log --oneline origin/main..main | wc -l
```
If non-zero, branch from local `main` instead — those commits are real, intentional, and the bundle should build on top of them:
```bash
git checkout -B bundle/<bundle-name> main
```
If zero (origin and local main agree), the original form is correct:
```bash
git checkout -B bundle/<bundle-name> origin/main
```
Naming pattern: `bundle/<area>-<theme>` (e.g., `bundle/runtime-builder-state-typing`). The branch is the unit-of-work for the entire bundle. All commits in Phase 4 land here; the Phase 6 PR (or local merge, see Phase 6a's hold-until-tag note) ships them together.
If the working tree is dirty when this skill is invoked, **stop** and surface the dirt — do not stash silently. The caller decides: commit, discard, or move out of the way. (Reason: per `feedback_commit_before_branch.md`, exploratory state must not get mixed into bundle commits.)
**Live-peer check (added 2026-08-16 v12).** A clean/acknowledged dirty-tree check at branch time is a snapshot, not a lock — it says nothing about whether another agent session is actively mutating the same checkout during EXECUTE. Before the first `git add` in Phase 4, and again immediately before every `git commit` in this bundle, call `ListAgents` (or the harness equivalent) and check for other **non-idle** sessions. If one is active on the same repo path, treat it as a hard-stop: wait for it to go idle before staging/committing, don't proceed on a guess. `git add <specific files>` does NOT protect against this — the index is shared process-wide, not per-agent-session, so a peer's `git commit` (even a plain `git commit -m ...` with no path args) sweeps up whatever you staged a moment earlier into THEIR commit. The only real isolation from a genuinely concurrent session is a dedicated worktree (`superpowers:using-git-worktrees`); the `ListAgents` check is the cheap mitigation when a worktree wasn't set up. (Reason: 2026-08-16 #198 spawn — a second live session's `git commit` on the same checkout swept 8 staged bundle files into an unrelated commit; recovery via `git reset --soft HEAD~1` itself raced the same peer recommitting mid-recovery. Caught only by manually running `ListAgents` and confirming the peer had gone idle before redoing the split.)
**Baseline capture (added 2026-05-21):** immediately after branching, pin the pre-EXECUTE state:
```bash
bun run build 2>&1 | tail -3 # → record "Tasks: N/N successful"
bun test 2>&1 | tail -3 # → record pass/fail/skip counts
```
Stash the numbers in the plan doc under a `## Baseline` heading. Phase 5 compares against these; pre-existing reds get filed as follow-up issues (see #93 pattern) rather than blocking the bundle. Without this baseline, a pre-existing failure surfaced by your edits looks like a regression and you'll burn budget chasing it.
---
## Phase 4 — EXECUTE
For each execution unit, follow `agent-tdd` discipline:
```
RED → write/find failing test demonstrating the issue
GREEN → minimum fix that turns the test
REVIEW → run review-patterns; address findings
COMMIT → conventional commit, citing GH issue numbers
```
**RED authority check (added 2026-05-25 v10).** Before relying on a RED test to pin a missing type or field, check **two harness conditions** that can silently mask the RED:
1. **Tests excluded from typecheck.** Run `grep -A2 '"exclude"' packages/<X>/tsconfig.json` — if `"tests/**/*"` is excluded, missing-type errors in the RED test will NOT fail typecheck. The "RED" passes against pre-fix state at type level.
2. **TaggedError / structural-type leniency.** Effect's `Data.TaggedError` stores any field passed to its constructor, even if the payload type doesn't declare it. `expect(err.newField).toBeDefined()` will pass against pre-fix state if the test constructs the error with `newField`. Same for plain TS structural types — passing extra properties to a struct constructor is accepted at runtime.
When either holds, the RED is post-hoc regression coverage only — it doesn't prove the pre-fix state was broken. Acceptable; just note in the plan's risk register and don't claim "test failed before fix, passes after" in the retro unless you confirmed it. To strengthen RED authority for type fields: write a temporary `src/.test-types.ts` smoke file that imports and destructures the new field, run `tsc --noEmit` on src/, then delete the smoke file before commit. Overkill for most fixes; flag only when the pre-fix RED must be authoritative.
**Fiber-interruption regression test construction (added 2026-08-16 v14).** When a regression test forks a fiber specifically to interrupt it later (proving fiber-supervised cancellation — e.g. "does interrupting this Effect actually stop the underlying work"), keep the fork, the wait-for-condition, and the `Fiber.interrupt` call inside ONE `Effect.gen` / single `Effect.runPromise` call. A bare `Effect.runPromise(Effect.fork(effect))` returns a `Fiber` handle, but the ephemeral scope created for that one `runPromise` call closes immediately after `fork` returns — which can interrupt the child fiber before the test ever gets to observe or deliberately interrupt it. This reads as "the fix doesn't work" (the condition you're polling for never becomes true) when it's actually a test-authoring bug, not a fix bug — verify with a quick throwaway debug script logging fiber state before concluding the production fix is wrong. (Reason: 2026-08-16 #35 spawn — a code-action Worker-interruption regression test's first draft forked outside the observing `Effect.gen`, silently self-interrupting before the sandboxed code reached its first tool call; cost several minutes chasing an unrelated red herring (`effect` version dual-package hazard in a `/tmp` debug script) before finding the real cause.)
(Reason: 2026-05-25 #75 spawn — RED test `parse-error-attempts.test.ts` was written expecting typecheck failure on `ParseAttemptError` not-yet-exported and `LLMParseError.attempts` not-yet-declared. Both conditions held: `packages/llm-provider/tsconfig.json` excludes tests; `Data.TaggedError` stored `attempts` field at runtime regardless of type declaration. The "RED" passed against pre-fix state. Fix still landed clean; lesson is to not over-claim RED→GREEN narrative in retros when these conditions hold.)
**Single-area mechanical-scaffold bundle template (added 2026-05-25 v10).** When N sites in **one package** share an identical scaffold (same imports, same control flow, same fix shape), prefer **mechanical in-place edit** over helper extraction. Heuristic:
| Condition | Action |
|-----------|--------|
| N ≤ 10 sites, same package, identical scaffold | Mechanical push/edit at each site. Verified-by = `grep -c '<new-pattern>'` returns N. |
| N > 10 sites, OR scaffold spans packages, OR scaffold has 3+ divergent variants | Extract helper. Test helper directly with mocked inputs. |
Mechanical edit wins on review surface (one shape to verify N times) and ships faster. Helper extraction trades that for de-duplication; only worth it when the dup cost exceeds the abstraction cost. (Reason: 2026-05-25 #75 — 5 providers × ~50 LOC identical retry loop. In-place push of 2 lines per provider beat extracting `parseStructuredWithRetry` helper on budget AND eliminated SDK-mock test complexity. Verified-by `grep -c parseAttempts.push` → 10 caught all sites in one check.)
**Dead-cast sweep (added 2026-05-21 v5).** Before migrating each cited `as any` site through a new helper, check whether the underlying type already supports the access pattern (the schema may have been tightened since the cast was added; the cast was historic). Delete dead casts outright — lighter diff, no helper indirection, less maintenance. Procedure for each site:
```bash
# Read the cited line's surrounding context
# Check the field's type in the schema (e.g., `packages/runtime/src/types.ts`)
# If the type already covers the access → delete the cast
# If `unknown` / `any` / missing field → migrate via the boundary helper
```
(Reason: 2026-05-21 #73 spawn — 2 of 9 cited `(c as any).selectedStrategy` casts were dead because `selectedStrategy` was already `Schema.optional(Schema.String)` on the schema. The casts were historic from a pre-typing era and could be deleted without any helper plumbing.)
**sed-after-Edit hazard (added 2026-05-25 v11).** When mixing the `Edit` tool (precise per-site) with bulk `sed -i 's/A/B/g'` in the same file/session, sed's pattern may **re-match Edit-wrapped sites** when the post-wrap suffix overlaps the search pattern's tail. Example: wrapping `fixedHandler(...)` with `asInterventionHandler(fixedHandler(...))`, then running `sed 's/registerHandler(dispatcher, fixedHandler(.*));$/.../' ` will re-match Edit-wrapped sites because both pre-wrap and post-wrap lines end with `));`. Result: extra paren on already-wrapped sites, syntax break, lost minutes.
Procedure:
```bash
# Before bulk sed, verify no prior-wrapped sites exist
grep -c "<post-state-tail>" <file> # e.g., grep -c "asInterventionHandler(fixedHandler" file
# If > 0 → DO NOT use sed. Use Edit with replace_all=true per unique site.
# If == 0 → safe to sed; verify with typecheck immediately after.
```
(Reason: 2026-05-25 #85 spawn — 4 Edit-wrapped sites at lines 104, 129, 130, 131 ended up with extra `)` after sed re-matched them. Caught by `tsc TS1005: ';' expected` within seconds; fixed with one `replace_all` Edit. Cheap to fix, but trivially avoidable by pre-grepping post-state.)
**Same-session multi-bundle protocol (added 2026-05-21 v5).** When chaining bundles in one session, **each subsequent branch MUST be created from `origin/main`, not from the previous bundle's branch.** Stacking bundles undermines the verified-by gate — a subtle regression in bundle 1 would mask in bundle 2's tests (or worse: cause bundle 2 to attribute its failures incorrectly). Each bundle:
1. branches off `origin/main` clean (`git checkout -B bundle/<name> origin/main`)
2. ships its own PR
3. is merged independently — never auto-merged
This session (2026-05-21 night+1) shipped #97 + #98 disjoint via this protocol; total ~1h45m. Worth pinning.
**Commit message template:**
```
fix(<package>): <short description>
Closes #N (bundle: <bundle-name>)
<one line on what changed>
<one line on what verified it>
```
**Test-path fallback (added 2026-05-21 v4):** if a planned RED integration test cannot reach the unit under fix after one debug round (e.g., wrapper registers but never fires), **stop debugging the test scaffold and switch to direct invocation**. Pull the registered handler/wrapper/helper from its registry (e.g., `RegistrationHarness._collected`, `LifecycleHookRegistry.list()`) and call it directly. Direct-invocation tests:
- pin the unit faster (sub-second runs vs full agent.run loops)
- isolate the fix from orthogonal config (provider, reasoning, scenario)
- match the cohesion signal: if the issue cites a *single file:line*, the test should hit *that line* without depending on a deep call chain
When in doubt, write the direct-invocation test first; expand to integration coverage only if multi-component interaction is actually under fix.
**Path-aware verified-by (added 2026-05-21 v4):** when a single file:line cited by an issue is fired from **multiple call-graph paths** (e.g., engine `LifecycleHookRegistry` AND harness `HarnessPipeline` both invoke the same hook handler), the issue's symptom may already be partially fixed by one path while the other still has the bug. Before locking the bundle scope, grep callers of the cited site and document in the plan which paths actually exhibit the symptom. The fix may be narrower than the verified-by suggests. (Reason: 2026-05-21 #74 — the engine path already escalated sync throws as defects through `Effect.catchAll`, surfacing them to `reactive-agent.ts:549` and firing `_errorHandler`. Only the harness duplicate-fire path was truly silent. A naive fix targeting "all hook error paths" would have overscoped.)
**Dead-code sweep (added 2026-05-22 v6).** Before applying the issue's prescribed fix, check whether the cited code is **dead in the current codebase state**. Deletion is preferable to migration/replacement when the original purpose is already satisfied elsewhere. The check applies broadly:
| Cited surface | Dead-code check |
|---------------|------------------|
| `as any` cast | does the underlying type already cover the access? → delete cast |
| `test.skip("RED…")` placeholder | did the targeted mechanism ship ✅ KEEP per phase-1/health-sweep evidence? → delete block |
| Helper function only referenced by deleted code | grep for inbound refs → delete |
| Interface/type only used inside a deleted span | same — delete |
| `TODO` on live code path | does the followup issue exist OR is the work obsolete? → wire or remove per HS-23 pattern |
When deletion is the right action, also confirm the issue's verified-by points at a stable external artifact (phase-1 evidence, MEMORY.md verdict, audit report) — that's what makes "delete" safe vs "replace with TBD". (Reason: 2026-05-22 #80 spawn — `m1-dispatcher-validation.test.ts:65` `test.skip("RED phase…")` was 110 LOC of placeholder. M1 had already shipped ✅ KEEP per `harness-reports/phase-1-mechanism-validation-2026-05-04.md`. Pure deletion was correct; replacement would have invented coverage that doesn't exist.)
**Pure-deletion verified-by (added 2026-05-22 v6).** When the bundle is purely deletion (no new helper, no migration, no replacement), the standard "grep target → 0" recheck is structurally weaker than for typing/refactor bundles. Strengthen by also asserting:
1. **Test count delta matches expectation.** If you deleted `test.skip(...)`, the package test runner's `skip` count should drop by exactly that number. Capture in retro alongside pass/fail.
2. **No inbound references remain.** For any symbol deleted (helper fn, interface, type), grep workspace-wide for references and confirm zero matches outside the touched file itself: `grep -rn "<DeletedSymbol>" packages/ | grep -v "<touched-file>"` → 0. If any inbound ref survives, your deletion shipped a compile-time break.
3. **No dangling imports.** `grep -n "import.*<DeletedSymbol>" packages/` → 0.
Failing any of these means the deletion missed adjacent dead-code; either expand scope or undo and re-bundle.
**Pause conditions (descope rather than skip):**
- Build goes red → revert unit, reopen issue with new failure mode, continue with remaining units
- Test suite gains net-new failures → same as above
- Effort blows past unit estimate by 2× → mark issue `over-budget` label, defer, continue
**Test+fix combo bundles (added 2026-05-22 v9).** When a behavioral RED test surfaces an impl bug during a test-coverage bundle, the fix lands in the same PR. The PR title combines verbs: `test(X): add coverage; fix Y`. Allowed when **all** apply:
1. The fix is ≤10 lines.
2. The fix mirrors an existing-working pattern in a sibling package, OR passes a code-reviewer agent for correctness.
3. The fix is covered by the same test that surfaced it (test serves as regression check).
If any of those fail, **descope**: file the bug as a separate issue and ship the bundle with the test marked `test.skip` / `xfail` referencing the new issue. (Reason: 2026-05-22 #82 vue portion — behavioral SSE-error test failed because `use-agent-stream.ts:76-78` threw inside an inner `JSON.parse try/catch` that swallowed it. Svelte sibling used direct assignment, no throw. 2-line mirror fix landed in PR #102 alongside the regression test. Defended over "test-only PR + separate fix PR" because the swallow is invisible to types and would have stayed latent.)
**Do NOT:**
- Skip tests for time pressure
- Use `as any` to silence types from the very issues you're closing
- Mix unrelated changes into a single commit (test+fix combo is NOT mixed — it's one observably-correct concern)
---
## Phase 5 — VERIFY (cross-cutting, after all units commit)
Run the bundle-wide verification gate:
```bash
bun run build # all packages green
bun test # full suite, no net-new failures vs pre-bundle baseline
bun run typecheck # workspace-wide
```
For each issue in the bundle, re-check the original verified-by claim against the new code state:
```
issue #N verified-by said: `grep -c "as any" packages/X/Y.ts` → 5
new check: `grep -c "as any" packages/X/Y.ts` → 0
✅ resolved
```
If a verified-by check fails to come down → the fix didn't actually address the claim. Reopen the issue with the new count + commit ref.
**Workspace-test-flake protocol (added 2026-05-22 v7).** When `bun test` (workspace, run from repo root) shows failures but per-package isolation runs clean, treat as test-order / fixture-state flake. Verification is acceptable when:
1. The bundle's touched package suite passes in isolation: `bun test packages/<touched>/` → 0 fail.
2. The failing tests live in packages NOT touched by the bundle. (`bun test packages/<failing-pkg>/` → 0 fail confirms it's flake, not real.)
3. The failing tests are not the verified-by recheck for any bundle issue.
Document the flake in the PR body (test name + isolation evidence). Do NOT block the bundle. CI may surface the same flake; if so, rerun the failed job. (Reason: 2026-05-22 #82 spawn — workspace `bun test` showed 2 fails in `packages/diagnose/`; `bun test packages/diagnose/` → 35/0. Pre-existing test-order issue, unrelated to the react smoke bundle. CI on #100 will rerun cleanly. Same pattern surfaced on #99 — `httpbin.org` external-network flake resolved on rerun.)
Track flakes that recur across ≥2 bundles in their own follow-up issue (e.g., "test-order flake in packages/diagnose under workspace `bun test`") — separately from any active bundle.
---
## Phase 6 — UPDATE
**6a — Open the PR (mandatory) — OR merge to local main (hold-until-tag repos only, added 2026-08-16 v13).** Every execution session ships its bundle as one PR against `origin/main`. Exception: if Phase 3.5's local-main-ahead check found local `main` running ahead of `origin/main` (this repo's own convention), a PR against `origin/main` right now would show every one of those unrelated unpushed commits as part of the diff, not just the bundle. In that case, merge the bundle branch directly into local `main` instead (`git checkout main && git merge --no-ff bundle/<bundle-name>`), verify the merged result (build + test), delete the bundle branch (local and any pushed remote copy), and note the deviation + why in the retro. Everything else in this phase (issue close, board move, knowledge sync) still applies — it just runs against the local-main merge instead of a merged PR.
```bash
git push -u origin bundle/<bundle-name>
gh pr create \
--base main \
--head bundle/<bundle-name> \
--title "<bundle-name>: <one-line summary>" \
--body "$(cat <<'EOF'
## Bundle: <name>
Closes #N
Closes #N
## Summary
<2-3 lines on what changed>
## Verification
- `bun run build` ✅
- `bun test` ✅ (delta: +X / -Y vs baseline)
- `bunx turbo run typecheck --filter=<changed>` ✅
- Verified-by rechecks (per issue):
- #N: `<command>` → <new result> (was <old>)
## Plan + Retro
- Plan: wiki/Planning/Implementation-Plans/YYYY-MM-DD-<bundle>.md
- Retro: wiki/Research/Debriefs/YYYY-MM-DD-<bundle>-execution-debrief.md
EOF
)"
```
PR body MUST include `Closes #N` for every issue in the bundle — GitHub auto-closes them on merge, no manual `gh issue close` needed. If a bundle issue was descoped mid-EXECUTE, drop its `Closes #N` line and explain in the PR body.
The skill's job ends at PR open. **Merge is a human decision** — do not auto-merge.
**6b — Project board + knowledge sync.** Move bundle issues to **In Review** column (not Done — done happens on merge). Then:
Sync local knowledge:
- `wiki/Hot.md` — append session note (bundle name, issues closed, key learnings)
- `.agents/MEMORY.md` — if a pattern emerged worth remembering, add a one-line entry under the relevant section
- `wiki/Issues/Running Issues Log.md` — if any HS-NN items closed, mark them in the migration table
---
## Phase 7 — RETRO (mandatory, self-improving)
Write a retrospective to `wiki/Research/Debriefs/YYYY-MM-DD-<bundle>-execution-debrief.md`:
```markdown
# Execution Retro: <bundle-name>
Date: YYYY-MM-DD
Budget: <budget_minutes> min | Actual: <actual> min
## Outcomes
- Issues closed: #N, #N, ...
- Issues descoped: #N (reason)
- Net test delta: +X / -Y
- Net LOC delta: +X / -Y
## What worked
- <one-line wins; reference commits>
## What didn't
- <friction points; missed estimates; surprises>
## Skill improvements (apply on next pass)
- <concrete change to SKILL.md — phase wording, gate, bundling heuristic, verification command>
- <e.g., "Bundling missed that HS-07 and HS-08 share a root cause — add 'shared untyped shape' as cohesion signal">
## Process inflation guard (HS-18/22/31 lesson)
- Did any unit's verified-by claim turn out to be inflated? If yes, document the inflation shape so the audit-finding template can catch it next time.
```
**Self-improvement loop:** the `Skill improvements` section gets applied to this very file before the retro is committed. Read this SKILL.md, find the section the retro says to amend, make the edit, commit alongside the retro.
This is non-negotiable. A bundle without a retro is not finished. A retro without a SKILL.md amendment leaves regression risk on the table.
---
## Anti-patterns to Reject
| Anti-pattern | Why it's banned |
|--------------|-----------------|
| "Just commit and we'll verify later" | Verification IS the deliverable; deferred = skipped |
| Closing an issue without re-running its verified-by | Pattern that produced HS-18/22/31 inflation |
| Bundling >5 issues for "efficiency" | Token + attention cost grows superlinearly; correlation between bundle-size and bug-introduction is documented |
| Cross-package bundles | Higher diff conflict risk; descope to per-package bundles |
| Retro that says "everything went great, no improvements" | Either (a) untrue (b) skill is at local maximum and needs harder scope — challenge the next run |
---
## Inputs This Skill Reads
- GH issues — `gh issue list ...`
- GH labels — existing taxonomy (`area:*`, `phase:*`, `priority:*`, `health-sweep`, `architecture-debt`, `verified`, `audit-2026-05-21`)
- `wiki/Hot.md` — recent state to avoid stepping on in-flight work
- `wiki/Issues/Running Issues Log.md` — historical context for HS-NN items
- AGENTS.md, CODING_STANDARDS.md — patterns the fixes must conform to
- Skill: `agent-tdd` — TDD discipline during EXECUTE
- Skill: `review-patterns` — gate before COMMIT
- Skill: `writing-plans` (with `wiki/Planning/Implementation-Plans/` override)
- Skill: `codebase-health-sweep` — for any opportunistic finding flagged during EXECUTE that wasn't in the bundle
## Outputs This Skill Writes
- Commits per execution unit (conventional format, citing GH #N)
- One bundle plan at `wiki/Planning/Implementation-Plans/`
- One execution retro at `wiki/Research/Debriefs/`
- GH issue closes + comments
- Project-board column moves
- Self-amendment to this SKILL.md (only the "Skill improvements" section can drive this; never silent edits)
---
## Recommended Invocation Patterns
**Solo run:**
```
/execute-backlog labels=audit-2026-05-21 priority=p1
```
**Parallel agent team (Extreme Ownership):**
Spawn one agent per `area:*` label with disjoint bundle scopes — each owns its area end-to-end. Coordinate via the tracker parent issue.
```
agent-providers: /execute-backlog labels=audit-2026-05-21,area:providers
agent-reasoning: /execute-backlog labels=audit-2026-05-21,area:reasoning
agent-harness: /execute-backlog labels=audit-2026-05-21,area:harness
```
**Daily/weekly cadence:**
Schedule via `/loop` — `/loop 1d /execute-backlog labels=priority:p1 max_bundle_size=3` — but ONLY if budget + verification rigor is non-negotiable in the loop body.
---
## Quick Reference Card
```
SCAN gh issue list --label … --json
BUNDLE greedy cohesion grow, cap at max_bundle_size
PLAN wiki/Planning/Implementation-Plans/YYYY-MM-DD-<bundle>.md
BRANCH git checkout -B bundle/<bundle-name> origin/main (clean tree only)
EXECUTE TDD per unit, conventional commits cite #N
VERIFY build + test + typecheck + re-run each verified-by
UPDATE gh pr create with Closes #N (auto-close on merge), board → In Review, Hot.md note
RETRO wiki/Research/Debriefs/, AMEND THIS SKILL.md
```
If any phase output is missing → the bundle is not finished. There is no "good enough."