Agent Skills: ticket-design

  <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 Design Summary section written into the ticket body containing:
  - Restated scope (refined further if D-phase surfaces gaps)
  - Artifact chain (which downstream artifacts will need creating or modifying)
  - Decision points (where future user touchpoints sit)
  - Risk areas (where the work is most likely to surface friction)

  If the user's redirects during D-phase reach three foundational
  reversals (per Lock 31), the skill recommends abort and offers to
  archive the bundle as research evidence for a fresh Q↔R session.

  Bundle state after this skill: ready for ticket-structure.
</output>

<key-responsibility>
  D is the alignment-or-loopback phase. Three outcomes are possible:

  1. **User confirms the design** → proceed to ticket-structure. This
     is the green-path outcome.

  2. **User redirects scope** → loop back to ticket-grill if the
     redirect reveals an un-grilled scoping gap. The redirect is
     logged in the Q&A file. Strike counter does NOT increment if
     the redirect is a NEW scope concern not previously locked.

  3. **User reverses a foundational decision** (one previously
     confirmed in Q↔R or in an earlier D-phase pass): strike counter
     increments. Three-strike escalation:
     - Strike 1: absorb, loop back to relevant phase, log reversal
     - Strike 2: surface concern — "bundle is becoming inconsistent;
       continue absorbing, or pause to consolidate?"
     - Strike 3: recommend abort — "three foundational reversals
       indicate original scoping was wrong; archive current bundle
       as research evidence, start fresh Q↔R?"

  Strike counter lives in session state; resets per session. The
  user can always insist on continuing past strike 3.
</key-responsibility>

<step n="1" title="Load Bundle and Initialize Strike Counter">
  <action>Load and execute: references/steps/step-01-load-bundle.xml</action>
  <note>
    Read the ticket (especially the Readiness Summary section written
    by ticket-grill), research file, questions file, and linked DRs.
    Initialize the session-scope foundational-strike counter to 0.
  </note>
</step>

<step n="2" title="Draft Design Proposal">
  <action>Load and execute: references/steps/step-02-draft-proposal.xml</action>
  <note>
    Compose the design proposal: artifact chain (what downstream
    artifacts will be touched), decision points (where future user
    touchpoints sit), risk areas (where friction is likely). The
    primary tag selects depth via the tag recipe (loaded from
    shared references when those exist; see Phase 4).
  </note>
</step>

<step n="3" title="Present and Align" critical="true">
  <action>Load and execute: references/steps/step-03-present-and-align.xml</action>
  <note>
    FIRM CHECKPOINT. Present the proposal to the user as a
    brain-surgery conversation: "Here is the journey this work
    requires; here are the decision points; here is where the risk
    lives. Does this look right?" User confirms, redirects, or
    rejects. Strike counter logic happens in step 4 — step 3 is
    just the presentation and capture of the user's response.
  </note>
</step>

<step n="4" title="Handle Redirects and Strike Escalation">
  <action>Load and execute: references/steps/step-04-handle-redirects.xml</action>
  <note>
    Classify the user's response. If confirm → goto step 5. If
    redirect-scope (un-grilled gap) → loop back to ticket-grill via
    explicit recommendation. If foundational reversal → increment
    strike counter and apply the strike-N protocol. If abort →
    archive the bundle and exit cleanly.
  </note>
</step>

<step n="5" title="Finalize and Handoff">
  <action>Load and execute: references/steps/step-05-finalize-and-handoff.xml</action>
  <note>
    Write the locked Design Summary into the ticket body. Stamp
    last_updated. Re-validate. Recommend ticket-structure as the
    next step via the ticketsmith menu.
  </note>
</step>

  Present the user with:
  1. The Design Summary that was written
  2. Bundle file paths (ticket, research, questions, any DRs)
  3. Strike counter status (if non-zero, note that prior reversals
     occurred this session)
  4. Next action: invoke `ticket-structure` from the ticketsmith
     menu (cmd: TS) to define the ticket's section/Parts shape.
</action>