aid-update-kb

Targeted KB Update

State machine: ANALYZE -> SCOPE -> CONFIRM -> APPLY -> REVIEW -> APPROVAL -> DONE (FIX loop inside REVIEW).

Analyzes how a prompt-driven instruction lands in the Knowledge Base, confirms the correct understanding and the exact scope with the user BEFORE any edit, then applies only that confirmed delta through the same review/calibration gate as /aid-discover. One pass per run -- each invocation drives the state machine to the next natural pause point.

Optional, off-pipeline. /aid-update-kb is NOT in the numbered phase-to-skill pipeline; no phase gate references it. It is an on-demand maintenance skill (like /aid-housekeep / /aid-ask).

Run-state is transient. Its run-state lives in a project-level file under .aid/.temp/ (.aid/.temp/UPDATEKB_STATE_<ts>.md, gitignored per .gitignore, removed at DONE) -- inside the skill's own Pre-flight-created worktree (AC-10), not the caller's tree. It does NOT write to any work STATE.md for its own run-state. The KB it edits has its own .aid/knowledge/STATE.md for review/approval history.

Boundary: prompt-driven-targeted vs source-driven-global. This skill is the prompt-driven-targeted half of the KB freshness loop -- the user supplies the scoping seed (the instruction) and ANALYZE + SCOPE turn it into a minimal Scope Plan. The source-driven-global sweep is aid-housekeep's KB-DELTA job. Docs that are domain-adjacent but not named by the instruction stay out of scope here (HL-5) and route to that sweep instead. The non-overlap contract between the two (FR-33/FR-34) is drawn in f010; this skill references that boundary but does not own it.

Human-gated, twice (NFR-6/C4/AC13, HL-1). Analysis and scope-planning are automatic; the change to KB content cannot proceed to APPLY without an explicit human [1] Confirm at CONFIRM (the root fix -- scope is vetoed BEFORE any edit exists), and cannot proceed to DONE without a second explicit human [1] Approved at APPROVAL. No auto-apply path exists at either gate.

State machine -- each /aid-update-kb invocation drives the state machine until it hits a natural pause point per .claude/aid/templates/state-machine-chaining.md. Mechanical states auto-chain; only PAUSE-FOR-USER-ACTION and HALT stop the run. Two human gates by design: CONFIRM guards scope/understanding BEFORE any edit; APPROVAL guards the specific edits before commit -- but a gate answered [1] inline is itself a CHAIN, not a pause (below).

aid-update-kb  > Pre-flight ISOLATE runs first, every invocation
  [ ANALYZE ] -> [ SCOPE ] -> [ CONFIRM ] -> [ APPLY ] -> [ REVIEW ] -> [ APPROVAL ] -> [ DONE ]
                                ^ human gate                             ^ human gate
                                [1] chains inline; [2]/[3] pause/halt

CONFIRM and APPROVAL are the two human gates -- inline decision points, not out-of-chat pauses. Per state-machine-chaining.md, a pause is only legitimate when the user has to do work outside the chat; answering an inline question is not that. Answering [1] (CONFIRM's Confirm / APPROVAL's Approved) is a CHAIN: the run continues straight through to APPLY / DONE within the same invocation (state-confirm.md's and state-approval.md's own [1] Advance lines say so explicitly, and the Dispatch table below agrees). Only the re-plan/cancel branches actually pause or halt: CONFIRM [2] Adjust loops back to SCOPE (or ANALYZE if the understanding itself changes) and PAUSES (a genuine re-plan needs a fresh clean-context SCOPE dispatch, which is real out-of-chat-equivalent work, not just an answer); CONFIRM [3] Cancel HALTs. APPROVAL [2] Additional consideration re-scopes back to CONFIRM/SCOPE (never blindly back to APPLY) and PAUSES for the same reason. REVIEW's FIX loop (REVIEW -> fix edits -> REVIEW) repeats until grade >= minimum_grade AND teach-back PASS AND act-back PASS, bounded to Confirmed Scope only (HL-7).