@boopkit/cap-workflows 0.2.2 → 0.2.4

package/skills/boop-refactor-dev-workflow/SKILL.md

@@ -24,10 +24,14 @@ This is the opposite instinct from feature work, and the difference is worth sta
 | The work is | capability that does not exist yet | every existing caller of a contract you are changing |
 | Progress looks like | vertical slices, each demonstrable | concept groups, none user-visible |
 | A green build means | the slice works | **possibly that you have not deleted enough** |
-| Completeness comes from | the Done-when and a demo | the compiler, a mechanical scan, and the suite |
+| Completeness comes from | the Done-when and a demo | the compiler, a search for the deleted name, and the suite |
 
 The central failure mode: **keeping the build green throughout a refactor is only possible by leaving a fallback** — a scalar, an optional-handle-with-default, a first-of-set pick — that silently absorbs the callers you have not converted yet. Every "additive, expand-contract, drop the old thing last" plan re-commits that sin, which is why it keeps producing refactors that look finished and leave an undetected tail.
 
+A scope boundary that leaves the old path callable is the same fallback under another name.
+"Runtime only; the pages keep showing the first item" and "defer the deletion to a later phase" both keep it alive.
+So whoever briefs, reviews or reports on a refactor checks that it began by deleting the old path and committed the red build, and calls a surviving optional parameter with a default unfinished.
+
 ## When this workflow applies
 
 - Changing a relationship's cardinality (one-to-one becoming one-to-many).
@@ -37,6 +41,9 @@ The central failure mode: **keeping the build green throughout a refactor is onl
 
 **When it does not apply:** adding new capability (use the feature workflow), or a change contained to one file with a handful of callers you can see at once. This workflow's overhead only pays when the call sites are too many to hold in your head — which is exactly when diligence-based approaches fail.
 
+It is also the wrong workflow for a change to a database that already holds rows, when the readers of those rows cannot all be updated at the same moment.
+Old and new code then have to run against the same data for a while, and that is the one case where expand-contract — add the new shape, move every reader, drop the old shape last — is the right method.
+
 ## The workflow
 
 ### 1. Establish the target vocabulary first, grounded in the code
@@ -54,6 +61,30 @@ Ground the vocabulary in the domain, not in the code's current names. If the cod
 ### 2. Decompose by concept group, not by call site
 
 One task per concept, ordered so that later concepts build on earlier ones. Enumerate-and-patch — a task per call site, each threading a handle through — always leaves a tail, because the list of sites is exactly the thing you cannot trust yourself to have enumerated.
+Add one more task beside the concept groups, for the verify stage in step 7, blocked by all of them.
+
+**Split a wide concept group at the compiler's checkpoints.**
+A concept group is as wide as its callers, and the widest can be more than one session's work.
+A session should not be run up to the model's context limit, because it slows down there and its judgement drops.
+How wide a group will turn out is hard to predict, but where to cut it is not, because the work falls into three stages and each ends on a state a command can check:
+
+1. Delete the old names and convert until the product code compiles, checked by compiling the product code alone, without the tests.
+2. Convert the tests until they type-check, checked by the whole-program static check over the product code and the tests together.
+3. Walk the test suites, as step 6 describes, until they pass.
+
+Make each stage its own issue, blocked by the one before it, so that each starts in a fresh session.
+Each stage issue carries the method like any other task, and its run scope says which check must be clean when it closes.
+The red the first two stages leave behind is intended: green is the end state of the group, not of each stage.
+Decide which groups are wide from the concept map — a deleted name that appears across dozens of files, or fixtures that reach most of the test tree — and leave a narrow group as one issue, since splitting it only adds cold starts.
+
+**Audit the issue bodies, then revise them, before the work starts.**
+Writing an issue and auditing it are separate passes, and doing both at once produces bodies that read well to their author and cost their reader time.
+Once every issue exists, re-read them all side by side as the agent who will claim each one cold, following the section "Write, audit and revise in three separate turns" in `boop-project-mgmt-beads-planning`, then rewrite whatever the audit finds.
+The go-red instruction in step 3 is the one most often lost to compressed wording, and an executor who misreads it keeps the build green with a fallback.
+
+**Put the test run scope on every issue.**
+Each issue runs the focused tests for what its group touches, plus the project's whole-program static check; the full suite runs once per branch, in the verify stage that completes it.
+The rule and the wording to put on each are in the section "Test run scope: what each task runs, and what runs once" in `boop-project-mgmt-beads-planning`.
 
 ### 3. Delete the escape hatch first, and commit the red build
 
@@ -64,30 +95,65 @@ If the build is still green after the deletion, a surviving hatch is absorbing t
 ### 4. Follow the compiler to green
 
 Fix each site by giving it the handle it needs, reading the set, or — only at a genuine display boundary — an explicit **commented reduction** (`set[0]` with a comment saying it is a render choice). Never inside a reusable resolver, where a write path can reach it.
+More generally, a site that keeps part of the old shape is legitimate only when a comment on that line says why; without one it is an unconverted call site.
 
 **A fallback is never correct.** Not a defaulted handle, not `?? oldThing`, not a first-of-set inside a resolver. If a call site genuinely cannot supply the handle, that is a **finding to surface**, not a fallback to invent. Green is the *end state*, never a state maintained throughout.
 
-### 5. Scan for what the types cannot see
+### 5. Loop on the compiler and a search, not on the test suite
+
+The compiler cannot see code that reaches the changed thing without a type.
+A read behind an inline cast (`as { field?: ... }`) re-declares the deleted field locally and compiles fine.
+So do a raw query naming a dropped column, a value read out of an `any`-typed blob, and a field name inside a template or a data fixture.
+The only tool that finds these is a search for the deleted name — the column, the field, the identifier — and for the inline-cast pattern, across the code, the templates and the data fixtures.
 
-A read hidden behind an inline cast (`as { field?: ... }`) re-declares the deleted field locally and compiles fine. After reaching green, grep for the cast pattern and for the deleted name in strings and comments. Also check loosely-typed call sites (`any`-typed blobs, raw queries, string-built SQL) — the compiler has no opinion there.
+**The conversion loop is: delete, let the compiler list the callers, fix them, search for the deleted name, fix what the search finds, and repeat until the static checks are clean and the search finds nothing.**
+Before the first deletion, confirm that both checks are clean on the unchanged tree, so every error they report afterwards is the refactor's own.
+If the project's static check does not cover the tests, widen it to cover them, because a fixture that still builds the old shape is a caller too.
 
-### 6. Run the full suite — it finds more than the compiler can
+The test suite is not part of this loop, and the reason is how directly each tool names the cause.
+The compiler names a file and a line, and the search names every occurrence; both are complete over what they cover.
+The suite reports one broken query as a cascade of failures in tests that never mention it, so it names symptoms where the compiler names the cause.
+A green static check is still a checkpoint, not the finish line: the compiler cannot see a writer that fails to fill the new field, or a value that now lands where no reader looks, and only running code finds those.
+That is the next step's job.
 
-Two whole classes of breakage are invisible to a type-check of the source:
+### 6. Walk the suites one at a time
 
-- **Fixtures** using the deleted shape, when tests are not in the source's type-check scope. Enumerate them with a widened check and migrate them forward.
-- **Writer-side and runtime gaps.** The compiler cannot see a *writer* that fails to populate the new field, or a value that now lands somewhere a reader does not look. Only the running suite does.
+Take the list of every suite from the test runner — all of them, not a list of failures — and walk it.
+Run one suite on its own; if it fails, read the failure, fix the cause, run it again, and move on.
 
-So the loop is always: **go red → follow the compiler → scan for casts → run the full suite → fix the writer gaps → repeat until green.** A green type-check is a checkpoint, not the finish line.
+**Do not collect the failures first.**
+A full run up front looks like it produces the work-list, and it actually manufactures one.
+Failures share causes: one missing method or one query naming a dropped column fails many suites at once, so a full run records one cause as many separate work items.
+A walk meets each cause once, in the first suite that reaches it, and by the time you arrive at the rest they pass.
 
-### 7. Prove it structurally, then hand off
+Nothing is filed during the walk; the suites you have not reached yet are the work-list.
+The only thing that becomes an issue is what cannot be resolved in the walk: a call site that genuinely cannot supply what the new contract requires, or a design question a person has to answer.
 
-Finish with evidence that does not depend on anyone's care:
+### 7. Verify — a stage, and an issue, of its own, ending in a punch list
 
-- The **mechanical scan** for every deleted pattern returns zero outside explicitly-commented display reductions.
-- A **real-path test at N greater than one** drives the actual surface to distinct outcomes — not a unit test of the new primitive, but the whole path, because concurrency and wiring defects only appear there.
-- The **full suite** is green.
-- Fold what changed into the reference docs, and leave the merge decision to the operator.
+Finish with evidence a reader can check without repeating the work:
+
+- **The search for every deleted name finds nothing**, except occurrences whose line comment says why they are deliberate.
+- **One test drives the real path end to end** — not a unit test of the new primitive, but the whole path, because concurrency and wiring defects only appear there. Where the change made something plural, drive it with three items and assert on the middle one.
+- **Every suite passes.** This is the one place in the workflow that runs them all.
+
+These checks are their own issue, a sibling of the concept groups and blocked by all of them, and a session that did not do the converting works it.
+The agent that converted the call sites is the worst-placed reader of its own work: it knows what it meant the code to do, so it reads that intention into the code.
+
+**Anything unresolved becomes an issue** under the same container, blocking the hand-off.
+A check that was never run counts as failed, since both leave the claim unproved.
+File one issue per cause, not per symptom.
+**A long punch list means the walk in step 6 was skipped.**
+Go back to the walk rather than filing every failure.
+
+**How to run and report the tests here.**
+Go through the project's test script, as "Go through the project's test script" in `boop-testing-testing` says.
+Write a run's output to a file and read the file, rather than piping it into a filter, so a wrong pattern does not force another run.
+A claim that the work is verified names the command, the counts and the commit, so a reviewer can check it without running the suite again.
+
+### 8. Hand off
+
+Fold what changed into the reference docs, and leave the merge decision to the operator.
 
 ## Principles that carry across the whole workflow
 
@@ -95,13 +161,25 @@ Finish with evidence that does not depend on anyone's care:
 
 **Verify the guarantee mechanism itself works.** "The compiler enforces this" is a claim worth testing. A type-check config that does not actually compile the files you think it does has been silently enforcing nothing.
 
-**Prefer three over two when proving a set.** Two is the weakest multi case: a first-of-set bug survives it whenever the arbitrary pick happens to match what the assertion reads. Use three, and assert against the middle one.
+**When the change made something plural, prefer three over two when proving it.** Two is the weakest multi case: a first-of-set bug survives it whenever the arbitrary pick happens to match what the assertion reads. Use three, and assert against the middle one.
 
-**Assert by name and by count.** Naming catches something missing; counting catches something doubled. A set-equality assertion reads identically whether an item was written once or twice.
+**When asserting over a collection, assert by name and by count.** Naming catches something missing; counting catches something doubled. A set-equality assertion reads identically whether an item was written once or twice.
+
+**When the new model gives a different answer from the shipped code, that is a design question, not a regression.**
+Do not patch a consumer back to the old output: that hides the question the refactor existed to raise.
+Record what the old code says, what the new model says, and which surface shows the difference, and leave the choice to whoever owns the design; an unattended session hands it back rather than choosing.
+If the new answer is right, update the copy, the tests and every surface that read the old behaviour; if the old one is right, narrow the new model.
 
 ## Running this unattended
 
-If the work is executed by autonomous agents, put **the method itself into each task's notes** — not just the task's scope. An agent picking up "make this field required" without the go-red discipline will keep the build green, which is the failure this workflow exists to prevent. Carrying the method on every task is what makes an unattended run trustworthy, and it is cheap: the same block on each issue, with a task-specific section.
+If the work is executed by autonomous agents, put **the method itself into each task's description** — not just the task's scope.
+The description is the copy that counts, because `boop loop` sends a session the issue's description and nothing else; the notes can repeat it.
+An agent picking up "make this field required" without the go-red discipline will keep the build green, which is the failure this workflow exists to prevent. Carrying the method on every task is what makes an unattended run trustworthy, and it is cheap: the same block on each issue, with a task-specific section.
+
+**Name the skills each task needs, too:** `boop-testing-testing` on every task, plus the skill for the layer the concept group changes.
+Write them as the skills list that `boop-project-mgmt-beads-planning` sets out in its section "Breadcrumb the skills that carry the discipline": a `## Skills` heading, the line "Before making changes, read each of these in full.", and a path to each skill's `SKILL.md`.
+The method is the one thing worth copying into an issue, because a fallback left in place cannot be corrected afterwards.
+Copy nothing else out of a skill: the copy in the issue is the one that goes stale without looking stale.
 
 ## Relationship to the feature workflow
 
@@ -110,6 +188,7 @@ A refactor of this kind usually exists to **make a feature buildable**. It ships
 ## Related
 
 - [boop-feature-dev-workflow](../boop-feature-dev-workflow/SKILL.md) — the peer workflow, for building capability.
+- [boop-architecture-audit-workflow](../boop-architecture-audit-workflow/SKILL.md) — when the structural change has not been chosen yet; it audits an area, grades its findings, and hands the survivors to this workflow.
 - `boop-product-design-engineering-design` — the concept map in step 1 is a design artifact; the current-state audit guidance applies.
-- `boop-testing-testing` — for the real-path proof in step 7.
-- `boop-coding-review-changes` — the scan in step 5 belongs in review too.
+- `boop-testing-testing` — for the real-path proof in step 7, and how to run the suites.
+- `boop-coding-review-changes` — the search for the deleted name in step 5 belongs in review too.

package/skills/boop-test-audit-workflow/SKILL.md

@@ -110,7 +110,21 @@ In the same session, while the classification is fresh, create one bd epic (an e
 
 **Keep the child count low, and group coarsely — at the suite level or higher.** Every child issue is a session for whoever runs it, and a fresh session reloads its context from scratch. Many small children multiply that cost and lose context between them. Prefer a few coarse issues, split by area or by suite rather than by file or by kind of change. Keep a removal together with the rewrite that covers its invariant, so one session cannot delete an old test before its replacement exists. Add one issue that confirms coverage and one that reviews the result. Ground each issue in the real test files it touches, and use `boop-project-mgmt-beads-planning` to shape the tree.
 
-Then create the bd tree and stop. Do not run the work yourself, and do not create the feature branch: the loop creates the worktree and its `work/<epic-id>` branch when it takes the first child. Creating the branch here collides with that and can strand commits.
+**Name the testing skills on every child.**
+A child's session sees the issue body and little else: not this workflow, and not the trim list unless the body points at it.
+Every child that rewrites or promotes a test carries `boop-testing-testing`, because the decision about a test's level (unit, pairwise, integration, seam) lives there, and the level is exactly what a rewrite gets wrong.
+Add the testing skill that matches the suite: the stack's (`boop-typescript-testing` in a TypeScript project) and, for routes, controllers and middleware, `boop-web-testing`.
+The children are all of one kind, so one named set covers the tree; write it once and put it on each child.
+Write them as the skills list that `boop-project-mgmt-beads-planning` sets out in its section "Breadcrumb the skills that carry the discipline": a `## Skills` heading, the line "Before making changes, read each of these in full.", and a path to each skill's `SKILL.md`.
+Names, not extracts: copy no method or checklist out of a skill into an issue, so that there is a single copy to keep current.
+The run-scope line is not an extract, and each child still carries it with the project's actual commands, as that skill asks.
+
+**Audit the issue bodies before the session ends, then revise them.**
+Writing an issue and auditing it are separate passes, and doing both at once produces bodies that read well to their author and cost their reader time.
+Once every child exists, re-read them all side by side as the agent who will claim each one cold, following the section "Write, audit and revise in three separate turns" in `boop-project-mgmt-beads-planning`, then rewrite whatever the audit finds.
+Some faults show only side by side: a child that says "a sibling issue handles this" without naming it, or a term the epic defines and a child then uses bare.
+
+Once the audited tree is in place, stop. Do not run the work yourself, and do not create the feature branch: the loop creates the worktree and its `work/<epic-id>` branch when it takes the first child. Creating the branch here collides with that and can strand commits.
 
 ### 6. How the children are executed (the loop runs them; these are the rules each one carries)
 Hand the finished tree to `boop loop --prefix <epic-id> --run`. Prefer `--reuse-session` for this workflow: every child has to re-read the invariant list and the trim list to make a correct keep-or-cut call, and carrying one session across the cluster is exactly the context a fresh-session-per-issue run would reload each time.
@@ -118,7 +132,7 @@ Hand the finished tree to `boop loop --prefix <epic-id> --run`. Prefer `--reuse-
 Write these rules into the child issues so each executing session follows them:
 
 - **The suite passes before and after.** This is a change to the tests, not to behaviour, so the tests in scope stay green throughout, and the only tests that stop existing are the ones the trim list marked for removal.
-- **Run tests per file or per small group, not the whole suite on each pass.** Re-running a large suite on every attempt is the biggest avoidable cost of this kind of work.
+- **Run tests per file or per small group, not the whole suite on each pass.** The file you just rewrote is the test that can tell you whether the rewrite holds, and a whole-suite run answers that question far less directly; this workflow makes hundreds of such passes, so the difference compounds.
 - **Change only tests.** Fixtures, factories, and test harness code count as tests and may change, which is what makes a promotion to a real-collaborator test possible. Production behaviour does not. If a rewrite uncovers a real bug — and a promotion often will, since it exercises a seam nothing exercised before — write a separate issue for it rather than fixing it in place.
 
 The review child then reads the whole branch and checks each change against the invariant it was meant to protect, not merely that the issue closed.
@@ -138,7 +152,8 @@ This is the work of the coverage and review children, and the loop's own closeou
 | Remove tests that do not exercise the purpose of the code, and re-level the ones written against the mechanism, without losing coverage | **this** |
 | Extend an existing system toward a goal, wiring new behaviour from parts that already exist | [boop-light-dev-workflow](../boop-light-dev-workflow/SKILL.md) |
 | Build a genuinely new subsystem, data model, or API from a spec | [boop-feature-dev-workflow](../boop-feature-dev-workflow/SKILL.md) |
-| Clear a noisy backlog of small lingering items in a themed sweep | [boop-issue-sweep-workflow](../boop-issue-sweep-workflow/SKILL.md) |
+| Clear a noisy backlog of small lingering items in a themed sweep | `boop-project-mgmt-issue-sweep-workflow` |
+| Audit a surface's production code for structural debt rather than its tests | [boop-architecture-audit-workflow](../boop-architecture-audit-workflow/SKILL.md), which depends on this workflow's verdict that the suite can catch a behaviour change |
 
 If the set of tests is small enough that the audit is a handful of edits with no real decomposition, skip the epic and do the rewrite under a plain bd issue. This workflow is for a surface big enough that classifying first, then executing, earns its keep.
 

package/skills/boop-design-handoff-workflow/SKILL.md

@@ -1,97 +0,0 @@
----
-name: boop-design-handoff-workflow
-description: "When the operator hands off a design package (a README plus a drop-in view template and CSS) for a redesigned surface, follow this process: read the README, VERIFY its claims against the real code, surface any buried decision to the operator, file an issue, run it as a sub-agent (branch for UAT or merge-on-clean-visual-check), then close out with knowledge integration and archival. The README is confident; confidence is not correctness — verify before you run."
-metadata:
-  category: workflow
----
-> **Read `PROJECT.md`, beside this file, first.**
-> It records how this project applies the guidance below, and where it deliberately differs.
-> Where the two conflict, `PROJECT.md` wins.
-> Record project-specific rules there, never in this file.
-
-# Design-handoff workflow — turn a design package into shipped, reviewed code.
-
-A design handoff package is a high-leverage input: someone has already done the design work and grounded it against the real view-model, so the implementation is mostly mechanical. The leverage is real, but so is the risk, and the risk lives in one place — **the README's claims about the existing code.** A handoff that says "the service already computes X, just re-expose it" is trivial if true and a hidden architectural decision if false. The whole process turns on verifying those claims before any code is written.
-
-## What a handoff package looks like
-
-Three files, typically grouped under a per-handoff directory in the project's design/eval reference area:
-
-- **`README.md`** — the authoritative spec. Names what is being built, which files it replaces, a "Data to surface" list (the view-model fields the redesign needs that the controller does not pass yet), what was deliberately dropped, and any follow-ons that are explicitly out of scope.
-- **A drop-in view template** — replaces an existing view. Every new field is guarded (rendered only when the field is present) with a live fallback, so the template renders *today* against the current view-model and "lights up" as each data field lands. Ship the template first, work the data list independently.
-- **A CSS file** — appended into an existing style block; its header comment names the rules it supersedes.
-
-## The process
-
-### 1. Read the README in full
-
-It is the spec — read it before touching anything. Note the "Data to surface" items (the view-model gaps), what it claims already exists, what it dropped and why, and the named follow-ons.
-
-### 2. Verify the README's claims against the real code (the load-bearing step)
-
-The README makes assertions about the current code: "X already exists," "Y was retired," "field Z is right there on the type," "this renders today with zero controller changes." **Every one of those is a feasibility claim, and each must be checked against the actual code before you judge the package.** This is the step that separates a clean run from a buried decision.
-
-- Confirm each "already exists" / "is right there" claim by reading the named symbol. (In a real run: a handoff claimed a field was "right there" — it was, on the underlying type, just dropped on the way to the view-model; trivial. Another claimed an upstream surface "already computed" a value — it deliberately did *not*, behind a documented boundary; that was a hidden architectural decision, not a re-expose.)
-- Confirm the template's "renders today" claim: the fields it depends on now exist on the view-model (or are provided by the controller), and the genuinely-new fields are guarded with a fallback.
-- Confirm any "retired" / "dropped" claim — a value the README says is gone may still be live and reusable.
-
-When every claim checks out, it is a clean single sub-agent run. When a claim is wrong — especially when "re-expose this" turns out to mean "reverse a deliberate architectural boundary" — there is a design decision hiding inside the package.
-
-### 3. Judge feasibility for a single sub-agent run
-
-Ask: is the work bounded with a clear path, or is there a judgment call hiding — an architectural decision, a premise error in the README, a spec ambiguity, a value that has to be derived rather than re-exposed? If the path is clear, it is one sub-agent run. If a decision is hiding, **do not let a sub-agent silently resolve it** (it will take the easy path — e.g. calling the function that reverses the boundary — because that is what "makes it work").
-
-### 4. Surface the verdict and any decision to the operator
-
-Report: feasible or not, the scope, and the one question that is genuinely theirs — the buried architectural decision, framed at their altitude with a recommendation. Use `boop-product-design-thought-partnership` here. Get the call, then bake the decision into the issue so the sub-agent inherits it rather than re-deriving it. (Example: "derive the value from the shared source, not by duplicating — the README's 're-expose' framing assumed an upstream surface already had it, which it didn't.")
-
-### 5. File a bd issue (goal/approach/context shape)
-
-Per `boop-project-mgmt-beads-planning`. Breadcrumb the handoff README as the authoritative spec, and **if the operator settled a decision in step 4, state it in the issue and say it supersedes the README where they differ** — otherwise the sub-agent will follow the README's wrong premise. Note the template's graceful-degradation (template + CSS can drop first; view-model edits light it up). Name the visual-check as the done-gate.
-
-### 6. Run it as a sub-agent
-
-- **Isolated worktree on a non-default port.** The operator's dev server on the main checkout (e.g. `:3000`) is theirs — never touch it. Create a worktree branch off main (e.g. `work/<id>`), run the worktree's dev server on a different port (`:3001`/`:3002`/etc.), copy `.env` in if tests/capture need it (gitignored, don't commit).
-- **Apply template + CSS**, removing the rules the CSS header names as superseded.
-- **Make the view-model edits** per the (corrected) data list.
-- **Trim brittle tests rather than lovingly rework them.** A redesigned surface is in flux; the operator's visual UAT is the safety net. Keep the full suite green; do not invest in expanding coverage on a surface that is still moving.
-- **The visual-check is the gate.** Build the CSS bundle, capture the affected states at desktop (1280) and mobile (390), and *read* the captures — the render is the proof, not the diff. (Auth caveat: the default capture tool may log in as a demo account and not reach the populated data you need; use a capture path that authenticates as the fully-populated account so the render shows real content.)
-- **Never `pkill` or pattern-kill a process** — an over-broad `pkill -f "<server command>"` can kill the operator's main-checkout server. Stop only your own server, by precise PID via `lsof -i:<port>`.
-- **Disposition:**
-  - **Branch for UAT** when the change is a substantial visual redesign the operator will want to see — leave the branch, the worktree, and the captures; do not merge, do not close.
-  - **Merge on a clean visual-check** when the change is quick, clear, and additive — merge to main only if the capture clearly confirms the result and tests are green; if verification is blocked or ambiguous, fall back to branch-for-UAT rather than merging blind.
-
-### 7. Close out (after the operator's UAT, or on a clean merge)
-
-Often itself a sub-agent. Per [`boop-knowledge-backfill`](../boop-knowledge-backfill/SKILL.md):
-
-- **Merge** the branch to main; run the full suite green first.
-- **Integrate the knowledge** — update the relevant reference page (e.g. the web-UI reference for a redesigned surface) to describe the new shape, and fix any reference line the redesign made stale. Commit docs direct to main.
-- **Archive the handoff package** (unedited) to `specs/history/<name>-handoff/`.
-- **Clean up** — close the issue, remove the worktree, delete the branch, stop the server by precise PID. Do not push to origin unless asked.
-
-## When to use this vs the other workflows
-
-| Situation | Workflow |
-|---|---|
-| A design handoff package (README + drop-in template + CSS) for a surface | **this** |
-| A goal-framed improvement to an existing surface, no package | [`boop-light-dev-workflow`](../boop-light-dev-workflow/SKILL.md) |
-| A backlog cleanup sweep of lingering P1/P2 items | [`boop-issue-sweep-workflow`](../boop-issue-sweep-workflow/SKILL.md) |
-| A feature with backend work driven by a spec | [`boop-feature-dev-workflow`](../boop-feature-dev-workflow/SKILL.md) |
-
-## Anti-patterns
-
-- **Running the package without verifying its claims.** The README reads as authoritative; authority is not accuracy. The verify-against-code step (2) is the whole game — skip it and you ship a hidden decision or hit a wall mid-run.
-- **Letting a sub-agent resolve a buried architectural decision.** When "re-expose X" actually means "reverse a documented boundary," a sub-agent will reverse it because that is the path of least resistance. Surface it to the operator instead.
-- **Auto-merging a substantial visual redesign without the operator's eye.** Branch for UAT. Reserve merge-on-clean-visual-check for quick, clear, additive fixes.
-- **Lovingly reworking brittle tests on a surface in flux.** Trim them; the visual UAT is the safety net. Reworking assertions that the redesign is about to invalidate again is wasted effort.
-- **`pkill`.** It can kill the operator's main-checkout server. Precise PID only, and never the main checkout's server.
-- **Following the README's premise after the operator corrected it.** If step 4 settled a decision, the issue must say it supersedes the README, or the sub-agent inherits the wrong framing.
-- **Taking a package's scope at face value against the full mockup.** A handoff package may be a *subset* of the designer's full vision: a package redesigned only the primary list and scoped the header and empty-state out as "unchanged," but the full mockup redesigned them too — the gap only surfaced at the operator's UAT. In step 2/4, confirm the package's scope against the full design mockup; a package that says parts are "unchanged / out of scope" may still leave the surface divergent from what the operator expects. Surface that at UAT.
-
-## Related
-
-- [`boop-knowledge-backfill`](../boop-knowledge-backfill/SKILL.md) — the archive + reference-integration discipline for the closeout.
-- `boop-web-web-ui-design` — the visual-check-before-done rule the run leans on.
-- [`boop-light-dev-workflow`](../boop-light-dev-workflow/SKILL.md) — the per-issue beats that run inside the sub-agent.
-- `boop-product-design-thought-partnership` — surfacing the buried decision at the operator's altitude.

package/skills/boop-issue-sweep-workflow/SKILL.md

@@ -1,180 +0,0 @@
----
-name: boop-issue-sweep-workflow
-description: "When the bd queue has accumulated a noisy backlog of lingering P1/P2 items — paper-cuts, small refactors, dead code, cosmetic bugs, taxonomy drift — and you want to clear them autonomously in a sequence that supports the week's goals, follow this process: inventory → cluster by theme → pick a cluster with the operator → run autonomously in one sweep worktree → hand off for a single UAT pass → log. The work lands in a worktree for one operator review rather than on main; it arrives with no decisions left in it."
-metadata:
-  category: workflow
----
-> **Read `PROJECT.md`, beside this file, first.**
-> It records how this project applies the guidance below, and where it deliberately differs.
-> Where the two conflict, `PROJECT.md` wins.
-> Record project-specific rules there, never in this file.
-
-# Issue sweep workflow — clear lingering backlog noise without spending the operator's judgment.
-
-The bd queue accumulates a long tail of lingering items: small refactors that didn't get done at the time, cosmetic bugs that nobody had cycles for, dead code that got noticed but not removed, taxonomy drift that someone filed and then moved on from. Each one is small. The cost is not the work; the cost is **carrying them in mind** — every `bd ready` listing them, every plan revisited with them open, every "should I do this now or later" decision. The mental load is the load.
-
-Issue-sweep clears that load. The workflow's deliverable is **one sweep worktree carrying N verified fixes, ready for a single operator UAT pass, with no decisions left in it** — not main with the issues already merged and closed.
-
-The load being cleared is **decision** load, not review load. The operator still looks at the result once, but they never have to answer a question to get there: N issues that each carried a "should I, and how?" collapse into one "does this look right?" That is a real reduction, and it is the only one the workflow promises. Anything that survives the run and grows the queue instead — a branch full of open questions, a findings doc to read, a follow-up issue to triage, a list of next steps to weigh — relocates noise from the bd list into the operator's review queue. That is not a reduction; it is a transfer.
-
-## When to use this vs the other workflows
-
-| Situation | Workflow |
-|---|---|
-| A backlog of lingering P1/P2 paper-cuts, small refactors, dead code, cosmetic fixes that the operator wants cleared in the background | **this** |
-| A concrete improvement to one existing surface, framed as a goal, whose design the operator wants to weigh in on | `boop-light-dev-workflow` |
-| A new feature with backend work driven by a spec | `boop-feature-dev-workflow` |
-| A page UX delivery campaign with a finding budget | `boop-ux-app-ui-dev-workflow` |
-
-The contrast with light-dev is no longer *where the work lands* — both end in a worktree the operator reviews. It is *what the operator has to bring to that review*. Light-dev hands back a change whose design the operator is expected to weigh in on. Issue-sweep hands back a batch of fixes that were only eligible because no weighing was needed, so the review is a look rather than a decision. If an issue requires operator judgment to ship — a copy choice, a design tradeoff, a fix path that isn't already named — it is not eligible for issue-sweep this pass, regardless of priority. The operator's judgment is exactly what the workflow exists to avoid spending.
-
-## Authority granted on launch
-
-When the operator invokes issue-sweep, they grant the agent authority — scoped to that run — to:
-
-- Create the sweep branch and worktree, plus a separate worktree for any item that routes as its own light-dev run.
-- Claim the issues it takes on, so they leave `bd ready` and stop presenting as open decisions.
-- Commit, run tests, run the visual-check for UI changes.
-- Close issues it finds were **already shipped** — those need no review, and the queue should shrink immediately.
-- Delete branches and worktrees for items it abandons.
-
-Two things the sweep may **not** do: merge to main, and close an issue as fixed before the operator has taken the worktree through UAT. Everything else stays on the worktree; issues it works stay **claimed and open** until sign-off. The audit trail is `git log`, the claimed/closed state in bd, and the append-only log file (below). This is a deliberate but bounded exception to the conservative-profile default in `CLAUDE.md`, scoped to the sweep run — a per-invocation grant, not a standing default. If the operator did not explicitly launch a sweep, none of this authority applies.
-
-## Stages
-
-### 1. Inventory
-
-**First, check that no sweep is already outstanding.** One sweep worktree exists at a time. If a previous sweep is still sitting unmerged, stop and say so rather than starting a second — an unmerged worktree the operator hasn't taken is the same mental load as an open issue, only harder to see, and two of them are worse than the backlog they replaced. The operator decides whether to take the outstanding one through UAT, rebase it onto current main, or abandon it.
-
-```bash
-git worktree list
-```
-
-Then read the open queue at P1 and P2 across all types:
-
-```bash
-bd list --status=open --priority=1
-bd list --status=open --priority=2
-```
-
-If both tiers are empty, fall back to P3. Do not filter by `--type=bug`; the workflow covers anything the operator carries in their queue — refactors, dead code, docs drift, paper-cut bugs, taxonomy decisions whose answer is already known, scaffolds that need finishing.
-
-**Then dedupe, before clustering.** The same problem gets filed repeatedly across sessions that could not see each other's work, and the duplicates rarely share wording — they share a *subject*: the same test, the same template, the same symbol, the same surface. Read the inventory for that subject rather than for matching titles.
-
-Where several issues turn out to be the same thing, pick one as the survivor and note the others as its duplicates. They then travel together: one investigation, one fix, and all of them close together on merge. This is the cheapest win the workflow has — it closes N issues for the cost of one, and more to the point it prevents N separate investigations of the same problem.
-
-### 2. Cluster by theme
-
-Group the inventory by surface or system theme, not by priority. Theme is the cheaper sort because issues that share a surface often share investigation cost. A first pass on a backlog might yield clusters like *one surface's paper-cuts*, *a status-taxonomy refactor*, *a CSS cleanup*, *an upstream-package batch* — and a handful of standalone items that don't cluster with anything.
-
-A cluster of one is fine. It means the item routes as a single light-dev-shaped run inside the sweep, not that it does not belong.
-
-### 3. Pick a cluster with the operator
-
-Propose one or two candidate clusters to the operator with a one-sentence rationale per candidate: how many items it carries, what surface it touches, whether it lines up with a named outcome in the project's active weekly next-steps doc, if one exists. The operator picks. **The picker is the operator, not the agent** — even though the rest of the workflow is autonomous, the selection step is where the operator's strategic judgment enters.
-
-The project's active weekly next-steps doc (if one exists) is one input, not a hard filter. A cluster that doesn't serve a named outcome may still be the right pick (correctness, developer-experience, mental-noise reduction). Goal alignment is a tiebreaker between otherwise comparable clusters.
-
-### 4. Decide the worktree shape
-
-The default is **one sweep worktree carrying the whole cluster**. Independent fixes that merely share a surface still belong in it: they are independent to *implement*, but they get reviewed together, gated together, and handed off together, so splitting them buys nothing while costing a worktree apiece.
-
-Split an item out into its own light-dev run and its own worktree only when it is genuinely larger than sweep-shaped — it needs its own design pass, its own review, or a UAT story that would be lost inside a batch. That is an escape hatch, not the common case. If more than an item or two in a cluster needs it, the cluster was mis-picked.
-
-Create the worktree from a **freshly fetched main**, and copy any local env files into it rather than symlinking — a symlink into a sibling worktree dangles when that worktree is removed.
-
-### 5. Run autonomously
-
-For each issue in the cluster, work through the light-dev beats (`goal → investigate → design → critique → implement → verify`), with the additions below, specific to issue-sweep.
-
-**The already-done check, before investigation.** Issues sometimes ship without being closed, or get partially addressed by unrelated work that touched the same code path. Before claiming an issue, look at the actual surface, the actual code, and the recent commits that touched it. Three outcomes:
-
-- **Already shipped.** The work is fully done. Close the issue with a one-line note pointing at the commit(s) that did it (`bd close <id> --reason="shipped in <commit>"`), record it under *Closed as already-done* in the log, and move on. This is the one close that does not wait for UAT, because there is nothing to review.
-- **Partially done.** Some of the work has shipped, some hasn't. If the remainder is itself autonomously fixable, finish it in the sweep worktree like any other item — it closes at merge, not now. If the remainder hides a judgment call, bail (same shape as the eligibility bail below) — leave a one-line note on the issue describing what's done and what's left.
-- **Not started.** Proceed to the eligibility check.
-
-This is cheap to run — one read of the relevant file or one `git log -- <path>` — and it prevents the worst paper-cut version of the workflow: an agent doing work that was already done, or re-litigating a decision the codebase already made.
-
-**The eligibility check at investigate-time.** During investigation, ask explicitly: *does this fix require me to pick between alternatives?* If yes — multiple reasonable approaches exist, the spec is ambiguous, the data model has a question hiding in it, the copy choice is not obvious — bail.
-
-The decision filter is the first gate, not the only one. Bail on any of the following too, regardless of how obvious the fix looks — each reaches past what a single unattended pass and a local gate can safely cover:
-
-- **Changes the database schema.** Migrations are coordinated; a sweep is the wrong vehicle even for an obviously-correct column addition.
-- **Has external side effects.** Anything that sends a message, calls a paid or third-party provider, touches real customer data, or deletes something not plainly dead.
-- **Changes dependencies, secrets, or environment config.** These fail in ways a local gate won't catch.
-- **Has unbounded blast radius.** See the stop-loss below.
-
-**Bail behavior:**
-
-- Add a one-line note to the bd issue via `bd update <id> --notes "issue-sweep skipped <YYYY-MM-DD>: needs decision on <X>"`. **Do not use `bd close` to record a bail, not even with `--reason="..."`.** A bail leaves the issue OPEN and visible in `bd ready`; closing it — even with a thoughtful close-reason — drops the issue out of the queue, which is the noise transfer the workflow exists to prevent. The bail note belongs in the issue's notes field; the issue's open status keeps it in the operator's review path.
-- Leave the issue in its current status. Do not file a follow-up issue, do not write a findings doc, do not update memory.
-- Move to the next item in the cluster.
-
-The skipped issue stays in the operator's queue exactly where it was. The operator periodically reaps the skipped ones and either decides them, promotes to feature-dev, or hands them back to issue-sweep with more guidance.
-
-**The stop-loss.** The eligibility check catches *this needs a decision*. It does not catch *this is simply bigger than it looked*. If a fix spreads past roughly three files, or its investigation keeps opening new ground, stop and bail (same shape as the eligibility bail) — it is a light-dev candidate that was mis-filed as a paper-cut. Sunk cost is the failure mode here; the twenty minutes already spent is not a reason to spend an hour more.
-
-**The "did I just decide something" critique.** In the critique beat from light-dev, in addition to the stranger test and the omission check, run an explicit check on the implementation itself: *did I pick between alternatives anywhere in the fix?* If yes, the issue was not actually eligible and the autonomy filter missed it. Revert the work, unclaim the issue so it returns to `bd ready`, apply the bail behavior above, and skip. False negatives (bailing on something that was actually safe) cost nothing; false positives (auto-deciding something operator-altitude) cost trust.
-
-**The verification gate before handoff.** A fix stays on the worktree only when:
-
-- Tests pass (`npm test` for the targeted area, full suite before handoff).
-- Build is green where relevant.
-- For UI changes, the visual-check from `boop-web-web-ui-design` is run: build the CSS bundle, capture the affected page at desktop and mobile widths, read the captures. A green test suite is not evidence that the surface looks right; only the render is.
-
-If verification fails, revert that fix and bail on its issue (same shape as the eligibility bail). Never hand back a red worktree, and never hold the whole batch hostage to one bad fix.
-
-### 6. Hand off for UAT
-
-Leave the sweep branch and worktree in place. Tell the operator what is in it: the branch name, the worktree path, the command to run the app against it, and the per-issue checklist from the log file below. The issues stay **claimed and open** until the operator has taken the worktree through UAT — claimed keeps them out of `bd ready`, so they stop presenting as decisions, and open keeps them honest, because nothing has shipped yet.
-
-Verify the whole batch on the worktree before you call it ready: full suite green, the visual-check done for every UI change, each fix confirmed against its issue. Handoff is a single checkpoint — one look for the operator, no open questions attached.
-
-After sign-off, the closeout is the usual one: merge the branch to main, close the shipped issues (`bd close <id1> <id2> ...`), then remove the worktree and delete the local branch. If the operator rejects one fix, revert its change, unclaim its issue with a one-line note, and merge the rest.
-
-### 7. Log
-
-Append a block to a sweep log file (e.g. `labs/issue-sweep/log.md`). Write it *during* the run rather than after, so it is ready at handoff: it doubles as the checklist the operator does UAT from and the record of what the sweep did.
-
-```
-## <YYYY-MM-DD> — <cluster name>
-
-Branch: <sweep branch>
-Worktree: <path>
-
-Shipped (UAT checklist):
-- <id> — one-line outcome — look at: <page or surface, or "tests only">
-- <id> — one-line outcome — look at: <…>
-
-Closed as already-done:
-- <id> — shipped in <commit>
-
-Bailed:
-- <id> — one-line reason (the decision needed, or the limit hit)
-
-Learned:
-- <pattern> → updated <skill-path>   (only if a skill edit was warranted)
-```
-
-No headers beyond the date+cluster line. No formatting ceremony. No calls to action. The "look at" note is what earns the file its keep at handoff: it is what turns N reviews into one pass. The audit trail is `git log` and the bd queue; the log is the human-readable summary the operator skims. If nothing was learned that warranted a skill edit, omit the Learned section.
-
-If the sweep discovers a pattern that warrants a skill update, the skill update lives in the skill — not in the bd queue and not in the log body. The log just notes the pointer.
-
-## Anti-patterns
-
-- **Handing back a decision.** The worktree is a single batched checkpoint, not a queue of open questions. A findings doc to read, a follow-up issue to triage, a "which of these did you want?" — each means the eligibility filter failed, because the operator is now spending exactly the judgment the sweep existed to save. The win is clearing decision load: the operator does one look and never answers a question.
-- **Merging to main yourself.** The sweep's authority ends at a verified worktree, and issues stay claimed-and-open until the operator has taken it through UAT. The one exception is an issue that turns out to have shipped before the sweep started: close that immediately, since there is nothing to review.
-- **Starting a second sweep while one is unmerged.** An unmerged worktree the operator has not taken is the mental load the workflow was supposed to remove, wearing a disguise.
-- **Investigating the same problem twice.** Duplicate filings are common and rarely share wording. Dedupe by subject at inventory, or pay the investigation cost once per filing.
-- **Auto-deciding a judgment call to keep the cluster moving.** The autonomy filter is restrictive on purpose. Skipping an eligible-looking issue because it turned out to hide a design call costs nothing; shipping a design decision the operator hasn't made costs trust.
-- **Filing follow-up bd issues during a sweep.** A sweep that closes three issues and files two is a wash, not a reduction. If a bail surfaces something worth tracking, the bail note on the original issue is the tracking. Skill edits go in the skill.
-- **Filtering by type at inventory.** Most P1/P2 items aren't tagged `[bug]`. Refactors, dead code, taxonomy decisions whose answer is known, scaffolds that need finishing — all are eligible if they're autonomously fixable.
-- **Letting goal alignment become a hard filter.** A P2 paper-cut that doesn't serve this week's named outcome is still a paper-cut. Alignment is a tiebreaker, not a gate.
-- **Skipping the visual-check for UI work because tests pass.** The render is the proof. A green test suite proves the structure compiles; only the capture proves the surface still looks right after the fix.
-- **Asking the operator mid-run.** The operator picked the cluster at stage 3; the rest of the run is autonomous. If a question arises that the operator would have to answer, that issue is not eligible — bail and move on, do not interrupt.
-
-## Related
-
-- [`boop-light-dev-workflow`](../boop-light-dev-workflow/SKILL.md) — the per-issue beat structure that issue-sweep uses inside its run stage. Each cluster item is a light-dev-shaped pass, with the eligibility filter and the shared hand-back worktree added on top. Both workflows hand back a worktree; the difference is whether the operator has to bring judgment to it.
-- `boop-web-web-ui-design` — the source of the visual-check rule for UI changes.
-- `boop-writing-technical-prose` — the translation test still applies to anything the agent writes (commit messages, log entries, bail notes).

package/skills/boop-knowledge-backfill/SKILL.md

@@ -1,28 +0,0 @@
----
-name: boop-knowledge-backfill
-description: "When you need to integrate new knowledge from a set of specs or completed work that was not documented in reference at the time it shipped. This often happens when a feature is developed under a tight deadline and the team prioritizes shipping over documentation, or when work was done before the reference system was fully established."
-metadata:
-  category: docs
----
-> **Read `PROJECT.md`, beside this file, first.**
-> It records how this project applies the guidance below, and where it deliberately differs.
-> Where the two conflict, `PROJECT.md` wins.
-> Record project-specific rules there, never in this file.
-
-# Knowledge Backfill
-
-   **a. Integrate into reference:**
-   - Follow the `boop-product-design-reference-integration` skill to blend the new feature's knowledge into existing `reference/` pages.
-   - This is NOT "create a new page for the feature" — it's merging knowledge into the existing concept pages (and creating new concept pages only when a genuinely new concept has no home).
-   - Update cross-links between affected reference pages.
-   - Remove or update any reference content that is now outdated.
-  
-   **b. Archive the spec:**
-   - Move the completed spec from `specs/` to `specs/history/` (create the directory if it doesn't exist).
-   - If any aspects of the spec were NOT implemented (deferred, descoped, or punted), extract those into a new revised spec in `specs/` that captures just the remaining work. Reference the archived spec for full context.
-   - The archived spec should be the full original — do not edit or trim it.
-
-## Related
-
-- `boop-product-design-reference-integration` — for step a of every spec you process; this workflow decides what to backfill and in what order, and that skill decides where each piece lands on the page.
-- `boop-writing-technical-prose` — when extracting the unimplemented remainder into a revised spec; that spec is read cold by someone with none of the backfill's context.