pcvelz/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

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.

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.

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