specifying-gates

# Specifying User-Thrown Gates ## When this skill runs Exactly one of: 1. A user-gate task has `"requiresUserSpecification": true` in its `json:metadata` fence, OR 2. The agent ran the "do I know HOW?" self-check (see `executing-plans`) and concluded the verification mechanics are ambiguous, OR 3. The user ran `/specify-gate <task-id>` manually. In all other cases — where `verifyCommand` is concrete and every `acceptanceCriteria` has an observable proof — the agent executes the gate directly and does NOT invoke this skill. **Announce at start:** "I'm using the specifying-gates skill to lock down verification mechanics for Task N." ## CRITICAL — what this skill does NOT do - Does not run the verification command. Specification only. - Does not close the task. It only enriches metadata; the agent returns to `executing-plans` afterward. - Does not re-run brainstorming. The design is already decided; only the HOW of one gate is missing. ## Input The target task ID. Resolved from the command argument or from the currently-in-progress user-gate task. Load the task with `TaskGet` and parse the `json:metadata` fence from its description. ## The four questions Use `AskUserQuestion` — one question at a time per the brainstorming skill's rule. ### Q1 — Observable outcome ```yaml AskUserQuestion: question: "Gate: <task subject>. What exact state proves this works? One line per criterion. 'It works' is not an answer — name a sensor, HTTP status, log line, file presence, or equivalent." header: "Gate outcome" options: - label: "I'll type the criteria" description: "Write 1-5 concrete, observable conditions" - label: "Copy from task's acceptanceCriteria" description: "Use the existing list (only if it's already concrete)" ``` Store the user's free-text answer as a list of strings in `acceptanceCriteria`. If any entry is vague (contains "works", "fine", "as expected", "properly" without a concrete target), push back and ask them to name the observable. ### Q2 — Proof mechanism ```yaml AskUserQuestion: question: "How should the agent capture that state?" header: "Mechanism" options: - label: "CLI command" description: "A shell command whose output shows the criterion" - label: "REST / API call" description: "HTTP request, inspect response" - label: "Subagent with briefing" description: "Dispatch Sonnet or Haiku with a prompt template" - label: "Direct inspection" description: "Read a file, query an entity, check a log" ``` If "Subagent with briefing" → ask Q5 (dispatch contract) before proceeding. If the user already named the live fixture in their brief, do NOT offer a "dry trace" proof mechanism — record the live command as the only `verifyCommand`. The specification is a lock, not a re-opening of a decision the user already made. ### Q3 — Scope ```yaml AskUserQuestion: question: "Run this once, or over multiple targets?" header: "Scope" options: - label: "Once" description: "Single execution, single target" - label: "Per instance / target" description: "Run identically across a list (e.g. all environments)" - label: "First on one, then on all" description: "Prove it on one target, then roll out to the rest — the classic two-gate pattern" - label: "Custom" description: "Describe the rule in free text" ``` Store as `gateScope`: `"once"` | `"per-target"` | `"one-then-all"` | custom string. ### Q4 — Failure policy ```yaml AskUserQuestion: question: "If the gate fails, what happens?" header: "On failure" options: - label: "Stop the plan (Recommended)" description: "No further tasks until this gate passes" - label: "Reopen this task, continue others" description: "Mark in_progress, keep the plan moving elsewhere" - label: "Log and continue" description: "Record failure, proceed — use only for informational gates" ``` Store as `failurePolicy`: `"stop-plan"` | `"reopen-continue"` | `"log-continue"`. ### Q5 (conditional) — Subagent dispatch contract Only when Q2 = "Subagent with briefing". ```yaml AskUserQuestion: question: "Paste the exact prompt / briefing the subagent should receive. This becomes the dispatch contract — the agent cannot substitute a shorter version at runtime." header: "Dispatch brief" options: - label: "I'll paste it" description: "Provide the briefing text" - label: "Use instances/<tag>/seed-briefing.md" description: "Per-target briefing file already written by a plan task" - label: "Generate from task description" description: "Build the briefing from the task's Goal + Files + Acceptance Criteria" ``` Store as `subagentBrief` (string or file-path). ## Writing back After all questions answered: 1. **Update the task description.** Rewrite the `json:metadata` fence with the new fields. Remove `requiresUserSpecification`. Keep everything else. Call `TaskUpdate` with the full new description. ```json:metadata { "files": [...], "verifyCommand": "<from Q2 — the CLI/API string, or '(subagent)' sentinel>", "acceptanceCriteria": ["<from Q1>", ...], "userGate": true, "tags": ["user-gate"], "gateScope": "<from Q3>", "failurePolicy": "<from Q4>", "subagentBrief": "<from Q5 if applicable>" } ``` 2. **Append a "Specification" section** to the human-readable part of the task description, above the `json:metadata` fence: ```markdown ### Specification (via /specify-gate on <ISO-date>) - **Outcome:** <Q1> - **Mechanism:** <Q2> - **Scope:** <Q3> - **Failure policy:** <Q4> - **Subagent brief:** <Q5 if applicable> ``` 3. **Sync `.tasks.json`.** Update the task entry's description and metadata, set `lastUpdated`. 4. **Announce:** "Specification locked. Returning control to executing-plans to run the gate." ## Handoff Control returns to `executing-plans`. The agent reads the updated task, executes `verifyCommand` (or dispatches the subagent with `subagentBrief`), captures output, and posts `AC: <criterion> — PROVEN BY <evidence>` per criterion before closing. ## What NOT to do in this skill - Do NOT invoke `ExitPlanMode` or `EnterPlanMode`. - Do NOT start the verification. The verification runs back in `executing-plans` after this skill exits. - Do NOT ask more than 4-5 questions. If the user's answers feel insufficient, prefer reopening with one follow-up over piling additional questions into the initial flow. - Do NOT write to disk anything other than the task description and `.tasks.json`. No side files. ## Integration - **Invoked from:** `executing-plans` (automatic), `/specify-gate` slash command (manual). - **Returns to:** `executing-plans`. - **References:** `skills/shared/task-format-reference.md` for metadata schema.