feat(aif-doctor): /aif-doctor operational-health triage skill (Class C runbook) - #404
Merged
Conversation
…C runbook) BUILD a thin $0 runbook over the existing helper layer + upstream read-only endpoints. Diagnoses aif-handoff env breakage (runtime crash-loop, capacity saturation, host-proxy block) the dispatch loop runs in — read-only sweep runs autonomously, every mutation gates behind operator GO (Q2 contract). - Reuses bridge-health.sh / verify-bridge.sh / ensure-parallel.ts + upstream /health + /agent/status (zero new scripts, zero npm deps, zero API-billed calls). - Catalogue = the 3 modes the upstream stale-watchdog cannot see, each with a live-verified detector->fix->reversibility (T15 bench, 2026-06-03). - SSOT #112 landed in this commit; Class C + doc-authority header; principle-15 paired-negative block. Prior-art: prior-art-evaluations.md#112 (/aif-doctor — BUILD runbook + REUSE helpers/endpoints; DeepWiki surfaced upstream /health, /agent/status, probeClaudeCli, recoverStaleInProgressTasks stale-watchdog — all reused/referenced; T16 verified watchdog problem-class = slow-stale auto-recovery vs ours = watchdog blind-spots). Companion to #111 /dispatcher. §1.7: forward+backward self-review at .claude/skills/aif-doctor/SKILL.md:169 (§9). Forward-check: complies with build-first-reuse-default.md:3 (BUILD runbook + REUSE helpers, full DeepWiki+WebSearch mechanism), no-paid-llm-in-ci.md:1 (zero API-billed calls), dual-implementation-discipline.md:6 (@cc-only-rationale marker), doc-authority-hierarchy.md:3 (Class C header), principle 15 (paired-negative). Backward-check: dispatcher SKILL.md:24 NOT-authoritative-for verified (names planning/pipeline/orchestrator only) — complementary, not superseded; bridge-health.sh reused unedited.
…en-ref on clean checkout The kickoff lives under .claude/orchestrator-prompts/* (gitignored; only done.md is tracked), so the markdown link resolved locally but 404'd in CI's clean checkout → principle 14 skill-drift FAIL. Demote to a plain code-span mention.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
New Class C skill
.claude/skills/aif-doctor/SKILL.md— an operator-side operational-health triage runbook for the local aif-handoff stack. Diagnoses why a task is stuck / runtime is broken / new tasks stay backlog, maps each failure mode to its existing helper or documented fix, and gates every mutation behind operator GO.Why: the
/dispatcherloop works, but the operating environment repeatedly breaks (runtime crash-loop, capacity saturation, flaky proxy) and nothing captured how to triage it — it was re-derived every session.Scope (3 files + 1 CI-fix)
.claude/skills/aif-doctor/SKILL.md— the runbook (Class C, doc-authority header, principle-15 paired-negative, §9 self-reflexive note).docs/meta-factory/prior-art-evaluations.md— SSOT feat(principles): principle 15 — skill paired-negative test (N2 #5, Commit B) #112 (verdictBUILD; runbook built, helpers/endpoints reused)..gitignore—!/.claude/skills/aif-doctor/negation (theaif-*glob targets AIF-installed consumer skills; this is framework-authored likedispatcher/pipeline)..claude/orchestrator-prompts/aif-doctor-skill/done.md— umbrella closure.BFR (full §3 mechanism)
SSOT consult + DeepWiki ≥3 + WebSearch ≥3 + adversarial counter-prompt → no upstream operator-facing aif health runbook. Reused upstream
/health,/agent/status, the stale-watchdog, andbridge-health.sh/verify-bridge.sh/ensure-parallel.ts. Zero new scripts, zero npm deps, zero API-billed calls.T15 bench — live-verified (the originating session's real symptoms)
cf8534d9crash-loops inplanningclaude --version→exec format error; native-binary dir empty; coordinator logClaudeRuntimeAdapterError … --omit=optional;/agent/statusheartbeatStale:false (watchdog can't catch it)backlog"active":3,"limit":3,"msg":"…pipeline at capacity, skipping"; cap unset→default 3curl registry.npmjs.orgtimeoutVerify-trace
BUILD; §1.7 commit-trailer added; skill-drift broken-ref fixed (de-linked gitignored kickoff.md)Anti-scope
Does NOT run the dispatch loop (
/dispatcher), plan (/pipeline), add deps, auto-mutate the runtime, or fix the host proxy tunnel (names it, stops). Separate observation:principle 20test is slow (27s) → flaky under pre-push timeout; pre-existing, unrelated.§1.7 Forward-check applied
The new skill complies with every active discipline layer, each verified against its source:
.claude/rules/build-first-reuse-default.md:3— BUILD-runbook + REUSE-helpers verdict via full mechanism (SSOT consult + DeepWiki ≥3 + WebSearch ≥3 + adversarial counter-prompt); SSOT rowdocs/meta-factory/prior-art-evaluations.md:182(feat(principles): principle 15 — skill paired-negative test (N2 #5, Commit B) #112)..claude/rules/no-paid-llm-in-ci.md:1— every probe iscurl/docker/grep; zero API-billed calls; the one paid path (API transport) is explicitly DEFER-gated..claude/rules/doc-authority-hierarchy.md:3— Class C + Authoritative-for/NOT header present (.claude/skills/aif-doctor/SKILL.md:20)..claude/rules/dual-implementation-discipline.md:6—@cc-only-rationalemarker at.claude/skills/aif-doctor/SKILL.md:18.packages/core/principles/15-skill-paired-negative.test.ts:49) —## Without this skill/## With this skillpresent and distinct.§1.7 Backward-check applied
Complete sweep of artefacts under this skill's scope; nothing superseded:
.claude/skills/dispatcher/SKILL.md:24— its NOT-authoritative-for header names only planning/pipeline/orchestrator (verified, silent on health) → this skill is complementary, not overlapping; trigger disjoint (dispatcherdisable-model-invocation:true)..claude/skills/pipeline/SKILL.md:1— untouched; planning stays pipeline's.packages/runtime-bridge/scripts/bridge-health.sh:15— REUSED unedited; its checks (dirty_worktree/dedup/park/net) confirmed NOT to cover the §3 modes (source read).docs/meta-factory/prior-art-evaluations.md:181— feat(principles): principle 15 — skill paired-negative test (N2 #5, Commit B) #111 dispatcher row unchanged; feat(principles): principle 15 — skill paired-negative test (N2 #5, Commit B) #112 appended, no renumber.