dos-unstick
**dos-unstick** analyzes a fleet's run archive to identify recurring blockers across multiple executions, normalizes each to a canonical cause from the workspace's declared reason vocabulary, clusters by recurrence and stall cost, and proposes one structural fix per cluster. Use this when the same blocking issue appears across multiple runs and you need to identify the root cause for a permanent fix rather than repeated manual interventions.
git clone --depth 1 https://github.com/anthony-chaudhary/dos-kernel /tmp/dos-unstick && cp -r /tmp/dos-unstick/src/dos/skills/dos-unstick ~/.claude/skills/dos-unstickSKILL.md
# dos-unstick — the recurring-blocker remediation sweep > **Stop the cause, not the instance.** A one-off unblock fixes today's stall; > `/dos-unstick` asks the different question — *what keeps blocking progress > across runs, and what one change would unblock it?* It mines the run archive, > normalizes every blocker to a canonical **cause key**, clusters the recurring > ones, ranks by recurrence × measured stall-cost, and proposes a **structural** > fix per cluster. Read-only; it writes no code and surfaces findings, never acts. The shape: **mine the trail → key each blocker → cluster the recurring ones → rank → propose a structural fix → surface.** The recurrence fold is the kernel's (`recurring_wedge`); the cause TAXONOMY is `[reasons]` data — a host adds a cause by declaring a reason, never by editing this skill. ## Inputs - `--runs <N>` (optional) — how many most-recent runs to sweep (default: a recent window). `--since <Nd|Nh>` overrides with a time window. - `--min-recurrence <N>` (optional) — a cause is "recurring" at N+ distinct runs (default 2 — the `recurring_wedge` `DEFAULT_MIN_RECURRENCE`). ## Step 0 — Discover the layout + the cause taxonomy ```bash dos doctor --workspace . --json ``` Read `paths.runs` (the run-archive dir to sweep) and run `dos man wedge` to read the **closed reason vocabulary** — the canonical cause keys this workspace knows. **Use these; never hardcode a run path or a cause string.** A cause the workspace cares about is a declared `[reasons]` entry, surfaced by `dos man wedge`. ```bash dos man wedge ``` ## Step 1 — Mine the run-archive trail Read the run records under `paths.runs` (read each once, sequentially — no tailing/polling, the very anti-pattern this sweep exists to surface). For each run that STOPPED on a BLOCKED / DRAIN / STALLED outcome, capture: the run id, the iteration, the blocker text, and the measured stall cost (`$`/wall) if recorded. > **No host evidence reader is wired by default.** A host that curates a > postmortem stream or a hand-ranked next-hits file can expose it as a > `dos.evidence_sources` driver hook; the generic sweep reads only the run-archive > verdicts. **`log` a one-line note when a host evidence source is not consulted** > — no silent gap (the `/dos-dispatch-loop` discipline). ## Step 2 — Key each blocker to a canonical cause Normalize each blocker text to ONE cause key from the declared `[reasons]` vocabulary (the host's cue table maps an Outcome-cell string to a key — the same kernel-catalog ↔ host-cue split `dos man wedge` documents). A blocker that maps to no declared cause is keyed `UNCATEGORIZED` (surfaced as a gap, never dropped). ## Step 3 — Cluster the recurring causes (the kernel fold) Feed the keyed blockers to the recurrence fold. It clusters by cause key, ranks by recurrence (dominant) × stall-cost (the tie-break), and tells you whether the cause the CURRENT sweep hit spans `>= min-recurrence` distinct runs: The fold is `recurring_wedge.classify_recurring_wedge` — pure, frozen-data-in, verdict-out. A cluster spanning ≥ `min-recurrence` runs is **recurring** (worth a structural fix); a one-off is noise the sweep cannot help. ## Step 4 — Propose ONE structural fix per recurring cluster For each recurring cluster, propose a **structural** change — a contract edit, an oracle rung, a preflight check — that would stop the cause RECURRING, not a one-off unblock of today's instance. Rank the proposals by the cluster's stall-score (recurrence × cost). The cause→fix mapping is the host's `[reasons]` fix-sketch (the reason's documented remediation), not a literal in this skill. ## Step 5 — Surface, don't act Route each proposal to the operator-decision queue: ```bash dos decisions add # the routing surface; the proposal is a finding, not an edit ``` This skill is **read-only**: it writes no code, edits no plan, takes no lease. A recurring cause is a finding for a human (or a follow-up plan), not an auto-applied change — the structural fix is a real engineering decision. ## What this skill deliberately does NOT do (no silent gap) - **No auto-unblock.** It proposes the structural fix; a human applies it. A loop that auto-unblocks would paper over the recurring cause, the exact failure mode. - **No curated postmortem / next-hits ingestion** unless a host wires a `dos.evidence_sources` hook. `log` when it is not consulting one. - **No trajectory mining** by default (the heavier read) — the run-archive verdicts are the generic floor. ## Anti-patterns - ❌ Proposing a one-off unblock for a 3-run recurring cause — that is the bug this skill exists to replace. Recurring ⇒ structural. - ❌ Hardcoding a cause string or a run path — read the vocabulary from `dos man wedge` and the path from `dos doctor --json`. - ❌ Tailing/polling the run dir — read each record once; polling is the waste this sweep surfaces in others.
Adjudicate a GitHub issue's "this is resolved" claim from witnesses the claimant didn't author — then close it carrying the evidence, or refuse with the typed gap. Use when an issue looks already-solved, after landing a fix that should have closed one, or to sweep open issues for silently-resolved ones.
Pick the next most important open GitHub issue this agent can actually complete, make its done-condition true, land it with witnesses (suite + parity + commit-audit), and priority-tag every issue touched along the way. Use when asked to "work the backlog", "complete the next most important issue", or to fix a specific issue number end-to-end.
Cut a versioned release of the DOS kernel — bump the version, draft release notes, commit, tag, push to master, and create a GitHub release. The tag push triggers the gated PyPI publish pipeline (publish.yml); the skill surfaces the run and its approval gate.
Promote an already-shipped rolling release (vX.Y.Z) of the DOS kernel to a named stable channel — gated on a green kernel suite + a green third-party CI run on the candidate + a clean truth syscall + a soak window. Writes an evidence file and adds a stable/<codename> git tag on the same commit. Does NOT bump versions or build new artifacts.
One automatic plan-class lifecycle tick. Reads the DECLARED class set + transition list from the workspace `[lifecycle]` table (not a hardcoded taxonomy), evaluates each trigger, spawns a read-only JUDGE-rung adjudicator (the `dos.judges` seam — advisory, fail-to-abstain) to approve/defer each candidate transition, applies the gated transitions as plan-meta edits + one commit per cycle, and logs to the run archive. Failsafes (per-cycle cap, per-plan cooldown, a veto class) are `[lifecycle]` data; the judge content is a host `dos.judges` driver. Every path/class comes from `dos doctor --json`. Use to garden a plan portfolio's lifecycle automatically, judge-gated. The DOS lifecycle gardener (SKP Axis 5, docs/207 Phase 5c).
Run /dos-dispatch on a recurring cadence, alternating with /dos-replan when the backlog drains — the dispatch→replan→dispatch cycle. The continue/stop/next-mode decision is the kernel's typed loop decision, not inline prose: each iteration is classified (`dos gate`) into a verdict and the loop's counters (drained-twice, the unclear/dirty-zero breakers, the iteration cap) drive the next step. Several loops on disjoint lanes run concurrently, each taking its own lane lease via `dos arbitrate`. Driven entirely by `dos` verbs + the workspace's `dos.toml`. The DOS reference loop workflow (SKP Axis 5).
End-to-end plan-and-ship for one lane — snapshot the portfolio with /dos-next-up, take a lane lease via `dos arbitrate` so parallel dispatches don't collide, gate the empty case via `dos gate`, ship the packet, and archive the run under the configured run dir. Driven entirely by `dos` verbs + the workspace's `dos.toml`; names no host path, lane, or commit convention. Use when you want to plan and ship the next batch on one lane in a single command, with concurrency safety. The DOS reference dispatch workflow (SKP Axis 5).
Ground a "keep working until the goal is met" stop condition in a witness the agent did not author, instead of letting the agent self-certify "done". A harness goal/Stop-hook condition is normally checked by the model re-reading its OWN work — consistency, not grounding. This skill turns the operator's goal into checkable EFFECT claims and wires `dos hook stop` so the Stop is refused until git ancestry (a shipped phase) or an effect read-back corroborates the claimed effect. Driven by `dos` verbs and the workspace's own `dos.toml` — no host-specific paths, lanes, or commit conventions. Use when you want a self-stopping agent (or a `/loop` worker) to be unable to declare a goal complete on its own say-so. The single-agent self-stop analogue of `dos-witness-claim`.