From bbb217d9a80cec060ac8500c9d69cbfaa6f26c8c Mon Sep 17 00:00:00 2001 From: Brummel Date: Fri, 19 Jun 2026 18:39:32 +0200 Subject: [PATCH] feat(boss): file skill-system deficiencies to the plugin's own tracker MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Under /boss only, when the orchestrator hits a durable deficiency in the plugin itself (a skill, agent, convention, or pipeline/cascade gap) mid-run, it files an issue against the plugin's own tracker and continues, marking provenance with a body block — no new label, so the fixed work-type vocabulary stays intact. Adds the trigger and its evidence gate (a citable path:line inside the plugin), dedupe-as-gate over open and recently-closed issues, and the discipline that filing is neither a notify event nor a substitute for a due bounce-back. Wires the new section into issue/SKILL.md (boss joins the issue-filing callers) and docs/conventions.md (Issue-tracker pointer). closes #9 --- boss/SKILL.md | 125 ++++++++++++++++++++++++++++++++++++++++++++ docs/conventions.md | 7 +++ issue/SKILL.md | 11 ++-- 3 files changed, 140 insertions(+), 3 deletions(-) diff --git a/boss/SKILL.md b/boss/SKILL.md index 2aac8c4..b628473 100644 --- a/boss/SKILL.md +++ b/boss/SKILL.md @@ -406,6 +406,10 @@ Mid-flow progress notifications burn the user's attention without giving them a decision to make. When in doubt, continue. +Filing skill-system feedback on the plugin's own tracker +(§ Skill-system feedback) is likewise not a notify event — it is +captured, not surfaced. + The notification command is `~/.claude/notify.sh` (the user-level convention); it receives the message text as a single argument. If it is unavailable, fall back to printing the notification in chat. @@ -506,6 +510,118 @@ pause. The boss-side contract is just this: fork was wrong — its own work only, never below the anchor, never a pushed commit. +## Skill-system feedback + +A `/boss` run executes *through* the skill system, so the orchestrator is +the one actor positioned to notice when the **plugin itself** is the thing +that is broken — not the project it is working on, but the toolchain doing +the work. When it hits such a deficiency mid-run, it files it as an issue +against the **plugin's own tracker** and continues. The forward-queue +discipline that governs a project governs the plugin too: a shortcoming +that is not written down is one that recurs on the next run. + +**What qualifies — a *durable plugin* deficiency.** Two conditions, both +required: the fault is in the plugin (a SKILL body, an agent, a +convention, the pipeline/cascade), and it would **recur** rather than +being a one-off. Positive triggers: + +- A skill or convention is self-contradictory, or ambiguous enough that + the orchestrator had to *guess* which reading was intended. +- A gate or agent returned a clearly wrong verdict traceable to a gap in + its own instructions — not to a project bug (that is `debug`, on the + project tracker). +- The entry cascade or pipeline had no path for a situation the + orchestrator legitimately reached, forcing it to improvise. +- An agent-template field, a status-protocol value, or a cross-reference + is missing, wrong, or dangling. + +**What does NOT qualify.** One-off project-specific friction; a project's +own missing config or facts; anything honestly attributable to the +*project* rather than the *plugin*. When unsure whose fault it is, it is +the project's — do not file against the plugin on a hunch. The evidence +gate makes this objective: if you cannot point to the offending +`path:line` *inside the plugin* that produced the wrong reading, it is not +plugin feedback — route it as a project bug (`debug`) or let it go. + +**Mechanics.** + +- **Target the plugin's own tracker, not the project's.** The run's + reference issue lives on the *project* tracker (§ Direction freedom); + this is a *separate* artefact on the *plugin's* tracker. Append + `--repo ` to each `tea issues` call (the override flag the + `issue` skill documents). The slug is this very plugin's repository — + derive it from the plugin checkout's git remote + (`git -C ~/dev/skills remote get-url origin`, the home the skills are + symlinked from), currently `Brummel/Skills`, so a fork or rename needs + no edit here. +- **When the project *is* the plugin, the two trackers still do not + coincide.** The skills meta-repo is not driven through `/boss` — it has + no project-facts queue (Step 1 finds no tracker) and is worked directly, + never through its own pipeline — so "the plugin's tracker" and "the + project's tracker" never resolve to the same place in a real run. (If a + run ever did execute with the plugin as its project, plugin feedback + would still take its *own* issue, distinct from the run's reference + issue, carrying the provenance block.) +- **Write it through `../issue/SKILL.md`.** Imperative title, declarative + voice, validated-or-flagged (cite the offending `path:line` inside the + plugin), self-contained. Work-type label from the normal vocabulary — + usually `idea`, `bug` if a gate misfired, `feature` if a path is + missing. No label is minted for provenance. +- **Mark the provenance in the body.** The body opens with a block stating + plainly that `/boss` filed it autonomously and which project the run was + on, so any later reader knows no human vetted it at filing time — then + the motivation and the problem description: + + ```` + > Filed autonomously by the `/boss` orchestrator while running on + > project "". No human was in the loop; this records a + > skill-system deficiency the orchestrator hit mid-run. + + ## Motivation + Why it matters — what the ambiguity or gap cost this run. + + ## Problem + The deficiency itself, with the offending `path:line` in the plugin. + ```` + +- **Dedupe, then file immediately.** The dedupe check is a gate in front + of the create, not an optional sibling step. One-shot it first — list + the plugin tracker's issues (`tea issues ls --repo `, open + *and* recently-closed). On an open match, comment there instead of + opening a duplicate. On a *closed* match, re-open or comment only if the + deficiency has clearly regressed, and treat a `wontfix`/by-design close + as a signal **not** to re-file — recurrence is exactly what the trigger + selects for, so a re-hit is expected, and re-litigating a settled close + is not the job. Otherwise create, the moment the deficiency is observed + (the context is richest then), and resume. Filing is a side-effect; it + never stops the loop. + +**Never a substitute for a bounce-back.** Filing plugin feedback +discharges no decision, so it can never stand in for one the user owns. A +situation can match *both* a plugin deficiency *and* a bounce-back trigger +(§ Direction freedom) — most sharply when a self-contradictory skill +leaves a *load-bearing* decision the orchestrator cannot derive past, or +when the missing pipeline path is really a new cycle. There the +orchestrator **bounces**, and may file the plugin issue *as well*: the +issue captures the plugin gap, the bounce captures the call the user still +owns. The capturable deficiency (a route-around-able wrong verdict, an +improvised-past missing path, a dangling cross-reference) is +file-and-continue; the blocking one is file-*and*-bounce. "The cascade had +no path, so I'll file a gap and keep going" is the exact dodge this +forbids. + +**Not a notify event.** Filing skill-system feedback is neither a +bounce-back (it asks the user for no decision) nor done-state. The filed +issue *is* the durable record; the user reviews the plugin tracker at +leisure. Notifying about it mid-run would be exactly the attention-burning +progress ping § Notifications forbids. It is also not a new outward-facing +action needing consent: it is the same issue-tracker write authority the +run already uses for its reference issue, pointed at a different repo. + +**`/boss`-only.** In interactive mode the user is present, so a noticed +shortcoming is simply surfaced in chat and filed via the `issue` skill if +the user wants it — there is no autonomous filing to govern. + ## Common Rationalisations | Excuse | Reality | @@ -527,6 +643,9 @@ pause. The boss-side contract is just this: | "There's an open fork — I'll bounce to `brainstorm` to be safe" | If you can *derive* an answer (sources, code, consistency, risk), decide it boldly and record it in the reference issue. Only a *pure-preference* fork bounces. Bouncing a derivable fork is exactly the timidity the bold stance retired; unsure if your leaning is bias, pull one ad-hoc `spec-skeptic` lens, then decide. | | "I derived a fork but didn't bother logging it on the issue" | The reference-issue comment is mandatory. It is the user's only window into a call made without them — and, because a rollback hard-drops the commits, the only surviving trace of the attempt. No reference issue, no fork decision: create the seeding issue first. | | "Auto-sign let me continue, so I don't need to notify — it's just progress" | The auto-sign notify is mandatory and carries a decision (the user's veto over a signature made without them). It is the one sanctioned mid-flow notify precisely because it is not progress — it is the audit trail for a delegated gate. | +| "I hit a gap in the skill system itself — I should notify the user about it" | No. File it on the plugin's own tracker with an autonomous-provenance body block and continue (§ Skill-system feedback). It needs no mid-run decision, so notifying would be the attention-burning progress ping the notify discipline forbids; the filed issue is the durable record. | +| "Something was awkward this run — file it against the plugin tracker" | Only a *durable plugin* deficiency qualifies: the fault is the plugin's (not the project's) and it would recur on the next run. One-off project friction is not plugin feedback; when unsure whose fault it is, it is the project's. File on the plugin tracker (never the project's), dedupe against its issues first, and mark provenance in the body — never with a new label. | +| "The cascade had no path here — file a plugin issue and keep going" | If that same situation needs a design call only the user can make (trigger 1) or is a new cycle (trigger 4), filing the plugin gap does NOT discharge the bounce-back. Bounce first; file the gap too (§ Skill-system feedback). Plugin feedback is captured-not-surfaced precisely because it carries no decision — so it can never stand in for one that does. | ## Red Flags — STOP @@ -545,6 +664,9 @@ pause. The boss-side contract is just this: - About to *decide* a fork that hangs on pure user preference (no derivable better) instead of bouncing it — or its inverse, bouncing a *derivable* fork to `brainstorm` out of timidity. - About to make a fork decision without recording it on the run's reference issue, or to run autonomously with no reference issue at all. - About to `git reset` below the session anchor, or to `reset` a commit that has been pushed — the rollback sandbox is the orchestrator's *own unpushed* commits above the anchor only; user-ratified and pushed history is forward-only (`git revert`). +- About to notify the user about a skill-system deficiency instead of filing it on the plugin's own tracker and continuing (§ Skill-system feedback) — it is captured, never a notify event. +- About to file plugin feedback for one-off project friction rather than a durable plugin deficiency, against the *project's* tracker instead of the plugin's, without deduping against the plugin's issues, or marked with a new provenance label instead of the body block. +- About to file a plugin-feedback issue *instead of* a due bounce-back — filing captures the gap but discharges no decision; if a bounce-back trigger also fires, bounce (and file the gap too). ## Cross-references @@ -559,6 +681,9 @@ pause. The boss-side contract is just this: external-service-consent rules that `/boss` does not lift. - **Queue:** the project's issue tracker — its CLAUDE.md project facts name the repo slug, the browsable URL, and the list command. +- **Issue-writing conventions:** `../issue/SKILL.md` — used both for the + run's reference issue on the *project* tracker and for skill-system + feedback filed on the *plugin's own* tracker (§ Skill-system feedback). - **Glossary write-rule:** `../docs/glossary-convention.md` — record-reality discipline for the only autonomous glossary writer. - **Spec auto-sign gate:** owned by `../specify` Step 6 — under `/boss` diff --git a/docs/conventions.md b/docs/conventions.md index 6b74457..4ccbb69 100644 --- a/docs/conventions.md +++ b/docs/conventions.md @@ -124,6 +124,13 @@ records its fork decisions on the run's reference issue there, and an ad-hoc `spec-skeptic` `scope-fork` dispatch reads single issues with their comment threads from there. +Separately, `/boss` files **skill-system deficiencies** — faults in the +plugin itself, hit mid-run — against the **plugin's own** tracker (slug +derived from the plugin checkout's git remote), provenance carried by a +body block and never a new label. The skills meta-repo is not driven +through its own pipeline, so this tracker and a project's tracker never +coincide. See `../boss/SKILL.md` § Skill-system feedback. + ## Pipeline The phase set, the gates, and the conditional dispatch are **fixed** diff --git a/issue/SKILL.md b/issue/SKILL.md index 61b2ecb..e52137f 100644 --- a/issue/SKILL.md +++ b/issue/SKILL.md @@ -30,7 +30,10 @@ is not a chat message. Other skills file issues through these same conventions — e.g. `brainstorm` parks a deferred spec as a backlog issue, `audit` files -regressions. This skill is the shared convention they lean on. +regressions, and `boss` files skill-system deficiencies against the +plugin's own tracker (with an autonomous-provenance body block — see +`../boss/SKILL.md` § Skill-system feedback). This skill is the shared +convention they lean on. ## The four writing rules @@ -145,5 +148,7 @@ Notes: - `~/dev/CLAUDE.md` — repo-English rule, label vocabulary, the `closes #N` commit convention (the tracker is the forward-queue). -- `../brainstorm/SKILL.md`, `../audit/SKILL.md` — callers that file - issues through these conventions. +- `../brainstorm/SKILL.md`, `../audit/SKILL.md`, `../boss/SKILL.md` — + callers that file issues through these conventions (`boss` files + skill-system feedback on the plugin's own tracker with an + autonomous-provenance body block, § Skill-system feedback).