Agent Skills: ticket-prototype

  <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>
  A prototype directory at {shared_folder}/tickets/{slug}/prototypes/{name}/
  containing minimal throwaway code. A findings block returned to the
  caller (ticket-grill) containing:
  - The question the prototype was answering
  - What was built (one-line summary)
  - How it was run (one command)
  - What was learned (factual findings, no opinions)
  - Path to the preserved prototype (for reference if needed later)

  The caller writes these findings into its bundle's research file.
  No separate prototype-findings document is created.
</output>

<key-responsibility>
  Prototyping is DISCOVERY, not DELIVERY. The agent must:
  - Resist over-engineering — prototypes are throwaway from day one
  - Resist documentation drift — findings go to the caller's research file, not a separate doc
  - Surface state aggressively — log/print/render intermediate state so the question gets answered
  - For UI: check for a design system and use it; ad-hoc styling produces misleading evidence about what the real product would look like
  - For LOGIC: keep it terminal — single-file scripts beat multi-file projects for a throwaway

  Per QRDSPIV: "Throwaway from day one, one command to run, no
  persistence by default, skip polish, surface state, delete or absorb
  findings when done. The answer extracted from a prototype belongs in
  the parent artifact (Brief, Spec, ADR); the prototype itself is
  evidence."
</key-responsibility>

<step n="1" title="Receive Question and Choose Branch">
  <action>Load and execute: references/steps/step-01-choose-branch.xml</action>
  <note>
    Read the question from the caller's context. Decide LOGIC vs UI
    based on the question's shape. Get user confirmation if the choice
    is ambiguous.
  </note>
</step>

<step n="2" title="Prepare Prototype Location">
  <action>Load and execute: references/steps/step-02-prepare-location.xml</action>
  <note>
    Resolve the bundle directory from the caller's context. Create
    {shared_folder}/tickets/{slug}/prototypes/{name}/. For UI:
    detect the project's design system (if any) and load its conventions.
  </note>
</step>

<step n="3" title="Scaffold Throwaway Files">
  <action>Load and execute: references/steps/step-03-scaffold-files.xml</action>
  <note>
    Create the minimal runnable. LOGIC: a single file (Python, TypeScript,
    shell — whatever fits the language ambient in the codebase). UI: an
    index.html plus minimal CSS/JS, design-system-aware. One-command
    runnable; no build step if avoidable; surface state aggressively.
  </note>
</step>

<step n="4" title="Run and Observe">
  <action>Load and execute: references/steps/step-04-run-and-observe.xml</action>
  <note>
    Execute the prototype OR present it to the user (UI prototypes
    usually require visual review). Capture observations. Iterate on
    the prototype only if the first run did not answer the question;
    cap iterations at 2-3 — beyond that, the question may be too
    complex for prototyping and should escalate to a spike ticket.
  </note>
</step>

<step n="5" title="Extract Findings and Return">
  <action>Load and execute: references/steps/step-05-extract-findings.xml</action>
  <note>
    Synthesize what was learned into a structured findings block.
    Return to the caller for inclusion in the bundle's research file.
    Preserve the prototype directory as a reference path. Do NOT write
    the findings to a separate prototype-findings doc.
  </note>
</step>

  The caller writes findings_block into the research file (in its own
  step-05 update-bundle-files); the prototype directory remains as a
  reference. The ticket-prototype skill itself does not write to the
  bundle's research file — that responsibility stays with the caller.
</action>