Agent Skills: ticket-grill

  <substep n="1a" title="Track Progress">
    <action if="first iteration">Create todo list from all instruction step titles (TodoWrite)</action>
    <action>Mark current step as in_progress (TodoWrite)</action>
  </substep>

  <substep n="1b" title="Handle Step Attributes">
    <check>If optional="true" and NOT YOLO -> Use Question tool to ask user whether to include (Yes/Skip)</check>
    <check>If if="condition" -> Evaluate condition</check>
    <check>If for-each="item" -> Repeat step for each item</check>
    <check>If repeat="n" -> Repeat step n times</check>
  </substep>

  <substep n="1c" title="Execute Step Content">
    <action>Process step instructions (markdown or XML tags)</action>
    <action>Replace {{variables}} with values (ask user if unknown)</action>
    <execute-tags>
      <tag>action -> Perform the action</tag>
      <tag>action type="script" -> Execute as shell command, capture output</tag>
      <tag>check if="condition" -> Conditional block wrapping actions (requires closing &lt;/check&gt;)</tag>
      <tag>ask -> Prompt user using Question tool and WAIT for response. When options exist, present them as selectable choices. For open-ended questions, provide helpful suggested options with custom input enabled</tag>
      <tag>invoke-skill name="skill-name" -> Execute another skill via OpenCode skill system</tag>
      <tag>invoke-agent name="subagent" prompt="task" -> Delegate to subagent via Task tool</tag>
      <tag>goto step="x" -> Jump to specified step (used for explicit loop-back in Q-R style flows)</tag>
    </execute-tags>
  </substep>

  <substep n="1d" title="Handle template-output Tags">
    <if tag="template-output">
      <mandate>Generate content for this section</mandate>
      <mandate>Save to file (Write first time, Edit subsequent)</mandate>
      <action>Display generated content</action>
      <action>Use Question tool to present checkpoint options. WAIT for response.
        <options>
          <option label="Continue" description="Approve this section and move to the next step" />
          <option label="Advanced Elicitation" description="Explore this section deeper before proceeding" />
          <option label="YOLO" description="Auto-complete the rest of this workflow without stopping" />
        </options>
        <if response="Advanced Elicitation">
          <action>Invoke advanced-elicitation skill</action>
        </if>
        <if response="Continue">
          <action>Continue to next step</action>
        </if>
        <if response="YOLO">
          <action>Enter YOLO mode for the rest of the workflow</action>
        </if>
      </action>
    </if>
  </substep>

  <substep n="1e" title="Step Completion">
    <action>Mark current step as completed (TodoWrite)</action>
    <check>If no special tags and NOT YOLO:</check>
    <action>Use Question tool to ask:
      <options>
        <option label="Continue" description="Proceed to the next step" />
        <option label="Edit" description="Revise this step before moving on" />
      </options>
    </action>
  </substep>
</step>

<step n="2" title="Completion">
  <check>Confirm all instruction steps have been executed</check>
  <output>Workflow complete.</output>
</step>

<output>
  An updated ticket bundle where:
  - The research file holds factual findings from subagent dispatch
  - The questions file holds every Q↔R exchange (question, chosen answer,
    rejected alternatives with brief why-not)
  - CONTEXT.md (or its per-context variants) reflects any terms resolved
    during grilling
  - Zero or more Decision Records have been scaffolded in
    {shared_folder}/decisions/ for hard-to-reverse decisions that surfaced
  - The ticket file's body has the user-request restatement and (if the
    loop concluded) the readiness summary; the design summary lives in
    ticket-design, not here
  Session state ready for ticket-design.
</output>

<key-responsibility>
  Grilling is patient work. The agent stays in this loop until the
  readiness criteria are GENUINELY met, not until impatience overrides
  them. Each turn:
  1. Reads the current bundle state
  2. Orients on what is known vs unknown
  3. Formulates one focused user-facing question OR a research agenda
  4. Dispatches subagents in parallel per the question-shape table
  5. Synthesizes findings, writes them to the research doc, logs the Q&A
  6. Checks readiness; if not ready, loops back to step 2

  The four Q↔R sub-activities (brainstorming, research, elicitation,
  prototyping) are mode-shifts within this loop, not separate phases.
  The "hide the intent" pattern from QRDSPIV applies only to
  implementation Q↔R, NOT here — ticket-writing grilling is open about
  what is being grilled.
</key-responsibility>

<step n="1" title="Load Bundle">
  <action>Load and execute: references/steps/step-01-load-bundle.xml</action>
  <note>
    Read the ticket, research, questions files, the Orient Summary
    breadcrumb from the questions file, and CONTEXT.md. This is the
    only step that runs once per session; all subsequent steps may
    loop multiple times.
  </note>
</step>

<step n="2" title="Orient on Current State">
  <action>Load and execute: references/steps/step-02-orient-current-state.xml</action>
  <note>
    Re-assess what is known and what is unknown after the last turn's
    findings (or, on the first turn, after the Orient Summary).
    Identify the highest-value gap to close THIS turn.
  </note>
</step>

<step n="3" title="Formulate Questions">
  <action>Load and execute: references/steps/step-03-formulate-questions.xml</action>
  <note>
    Split the turn's questions into:
    - User-directed (asked immediately via Question tool — firm checkpoint)
    - Research agenda (dispatched to subagents in step 4)
    - Artifact checks (e.g., reading specs, briefs, existing thoughts/ docs)
  </note>
</step>

<step n="4" title="Dispatch and Synthesize">
  <action>Load and execute: references/steps/step-04-dispatch-and-synthesize.xml</action>
  <note>
    Dispatch 2-4 subagents in parallel per the question-shape table at
    references/subagent-dispatch.md. Wait for ALL to return. Synthesize
    findings into the research file. This step never runs serially —
    parallel is mandatory.
  </note>
</step>

<step n="5" title="Update Bundle Files">
  <action>Load and execute: references/steps/step-05-update-bundle-files.xml</action>
  <note>
    Write the turn's Q&A to the questions file (one entry per resolved
    question with the chosen answer + rejected alternatives + brief
    why-not). Update CONTEXT.md inline if any terms were resolved
    (via context-md-format skill). If a hard-to-reverse decision
    surfaced and the three-condition gate fires, scaffold a Decision
    Record (via decision-record-format skill and
    scaffold-decision-record.py). Stamp last_updated on every modified
    bundle file.
  </note>
</step>

<step n="6" title="Readiness Gate">
  <action>Load and execute: references/steps/step-06-readiness-gate.xml</action>
  <note>
    Check all five readiness criteria. If any is not yet true, present
    the gap to the user with a Question tool checkpoint and loop back
    to step 2. If all five are true, present the readiness summary
    and hand off to ticket-design.
  </note>
</step>