checking-gates

# Checking User-Thrown Gates ## Why this skill is separate from executing-plans User-gate enforcement is an **opt-in flow**. When the opt-in hook is not registered, executing-plans runs unchanged — no extra checks, no extra context, no extra questions. When the hook IS registered, it routes user-gate tasks through this skill. Keeping the decision logic in a separate skill means: - Users who don't want the flow get zero friction. - Users who do want it get a focused, scoped handler. - `executing-plans` stays short and readable. ## When to invoke Any one of: 1. You are about to start a task whose `json:metadata` has `"userGate": true` or whose `tags` contains `"user-gate"` AND the opt-in hook is active (see the README for how to detect this — if you were invoked via `/gate-check`, the hook is active by definition). 2. A hook fired stderr telling you to run `/gate-check <task-id>`. 3. The user manually ran `/gate-check <task-id>`. If none of these apply, return to executing-plans without running this skill. **Announce at start:** "I'm using the checking-gates skill to verify Task N's acceptance criteria." ## The three-step process ### Step 1 — Load and classify 1. `TaskGet <task-id>` — read the full description. 2. Parse the `json:metadata` fence. 3. Classify: - `requiresUserSpecification: true` → go to Step 2 path A. - Concrete `verifyCommand` + every `acceptanceCriteria` names an observable (sensor, HTTP status, file, log line, entity) → go to Step 2 path B. - Vague criteria ("it works", "is fine", "as expected", "properly") or missing `verifyCommand` → go to Step 2 path A. ### Step 2 — Route **Path A — HOW is ambiguous.** Invoke `specifying-gates` (or tell the user to run `/specify-gate <task-id>`). Stop. Let that skill lock down the mechanics. When it returns, re-enter this skill from Step 1. **Path B — HOW is clear.** Continue to Step 3. ### Step 3 — Execute and post evidence 1. Run the `verifyCommand` (or dispatch the subagent with `subagentBrief`). Capture exact output. 2. Map each `acceptanceCriteria` entry to an observable in the output. 3. Post one block of text back to the user, using EXACTLY this format (the sibling hooks key off the `AC:` + `PROVEN BY` markers): ``` Gate: <task subject> AC: <criterion 1> — PROVEN BY <command or excerpt of output> AC: <criterion 2> — PROVEN BY <...> ... ``` 4. If every criterion passed → `TaskUpdate status=completed`. 5. If any criterion failed → look up `failurePolicy`: - `"stop-plan"` → leave the task `in_progress`, surface the failure to the user, stop. - `"reopen-continue"` → leave the task `in_progress`, move to the next unblocked task. - `"log-continue"` → post the failure inline, mark completed anyway, continue. ## Do-I-know-HOW self-check — the short version A criterion has a clear HOW when all three hold: 1. **Observable named** — sensor entity, HTTP endpoint, file path, log pattern, entity ID. Not "state", not "result". 2. **Capture method named** — the command, API call, subagent, or direct read that produces the observable. 3. **Pass/fail rule named** — an exact value, regex, or threshold. Not "reasonable" or "correct". If any of the three is missing for any criterion, HOW is NOT clear → Path A. **Err on the side of Path A.** Inventing a HOW silently is the exact failure this flow exists to prevent. ## What NOT to do - Do NOT modify executing-plans' behavior from inside this skill. This skill is a leaf — it returns control when done. - Do NOT invoke `EnterPlanMode` or `ExitPlanMode`. - Do NOT substitute a cheaper verification for the one specified. If you think the spec is wrong, reopen via `/specify-gate` — don't walk around it. - This prohibition also covers *re-asking* a settled approach absent a changed condition — not just substituting inline. Surfacing "should we do the lesser check instead" for a verification the plan already fixed is walking around the gate unless a material condition changed (different fixture/branch, new blocker, broken plan assumption). - Do NOT close the task if any criterion lacks concrete evidence. "Looks fine" is not evidence. ## Integration - **Invoked from:** the PostToolUse / PreToolUse user-gate hook; or `/gate-check` slash command. - **May hand off to:** `specifying-gates` (Path A). - **Returns to:** `executing-plans` (or wherever it was invoked from) after TaskUpdate. - **References:** `skills/shared/task-format-reference.md` for metadata schema.