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

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

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

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

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".

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:

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.