| name | dos-unstick |
| description | Analyze BLOCKED/DRAIN run history, cluster recurring causes, and propose one structural fix per wedge via `dos decisions`. Use when a fleet keeps stalling and you want a systemic unblock rather than another manual nudge. |
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
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.
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:
dos decisions add
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.
