@boopkit/cap-workflows 0.1.1 → 0.2.0

package/capability.json

@@ -15,6 +15,7 @@
     "boop-issue-sweep-workflow",
     "boop-website-dev-workflow",
     "boop-design-handoff-workflow",
-    "boop-knowledge-backfill"
+    "boop-knowledge-backfill",
+    "boop-stray-disposition"
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@boopkit/cap-workflows",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Reusable end-to-end development and writing workflows for AI agents",
   "files": [
     "skills/",

package/skills/boop-stray-disposition/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: boop-stray-disposition
+description: "When an autonomous run (a loop, a sweep, a sub-agent session) has finished and filed follow-up issues along the way, settle each one before you write the closing summary. Every stray gets a recorded disposition — re-parented and reachable from the roadmap, folded into a spec and closed, or triaged away. Use this whenever a run ends with issues in the queue that nobody has decided to do."
+metadata:
+  category: workflow
+---
+
+# Stray disposition — settle what a run filed before you call it done
+
+Agents working through an autonomous run routinely file follow-up issues during review and
+punch-list work without parenting them to the epic they arose from. Those issues land in the
+ready queue disconnected from the context that produced them. After every run, before the
+closing summary, audit for these strays and give each one a **disposition** — the deliberate
+settling of what becomes of it — so nothing is left in limbo.
+
+Find them by running `bd ready` and `bd list --status=open` and identifying the issues this run
+filed: they cite the run's findings or the files it touched.
+
+## The three dispositions
+
+1. **Re-parent** — the stray belongs to the work that just ran. Move it under the run's epic, or
+   group several strays under a new discovered-from epic (`Group: <work> hardening`) for a
+   follow-on run scoped to that prefix on the same branch, so the operator still reviews and
+   merges once.
+
+2. **Fold** — the stray is requirements or evidence for a spec that is already planned. Move the
+   substance into that spec's text and close the issue with a reason pointing at the spec. A
+   future run plans from the spec, never from the closed queue, so content left behind in the
+   issue would never reach it.
+
+3. **Triage** — a true orphan. Close it with a reason if it does not survive scrutiny, or surface
+   it to the operator in the closing summary for a decision. Never leave it silently in the queue.
+
+## Re-parenting alone is not a disposition
+
+Nothing polls or sweeps the issue queue. Work reaches an agent only through the plan spec and the
+runs it launches. A stray moved under an epic that no planned run will execute is still stranded —
+just tidier.
+
+A disposition is complete only when the stray is **reachable from the roadmap**: the plan spec
+names the issue and the trigger for picking it up, or the substance is folded into a spec, or the
+issue is closed.
+
+If the stray must wait on an event, encode the sequencing as a dependency (`bd dep`) on the issue
+that produces that event. A dependency is visible and self-releasing. Deferring an issue only
+hides it from the ready queue until a date, which helps nobody who is not already polling.
+
+## Fold versus reference is a judgement call
+
+**Fold** — extract the substance into the spec so it reads complete cold, close the issue, and
+leave pointers at both ends — when the next reader is a planner working from the spec.
+
+**Keep the issue open and give the spec a one-line reference instead** when the finding is
+operational rather than design-shaped (a bug with reproduction steps that will be worked *as* an
+issue), when the issue is a living artifact with discussion or an owner, or when the content is
+too bulky to fold without bloating the spec.
+
+The test under both: put the substance where its next reader will actually look, and leave a
+pointer at the other end.
+
+## Archiving a spec orphans the issues it rooted
+
+When closeout moves a spec to a history location, any open issue whose only roadmap reference
+lived in that spec is stranded again. Migrate those references to the successor document — the
+remainder spec, or the plan — as part of the same sweep.
+
+## The test at the end
+
+Every stray filed during the run has a recorded disposition, each disposition ends at the roadmap
+or at a closed issue, and the ready queue contains only work someone has actually decided to do.
+
+A queue that accumulates undispositioned findings makes every future `bd ready` call more
+expensive to read. That noise is what this practice exists to prevent.
+
+## Related
+
+- `boop-project-mgmt-beads-planning` — how to write and parent the issues a disposition re-parents
+  or folds, so the next agent can pick one up cold.
+- `boop-issue-sweep-workflow` — when the strays have already accumulated into a backlog and want
+  clearing as a batch rather than settling one run's output.