Start

---
description: Kick off GitHub issue work session with branch setup, project updates, and planning
---

You are an AI coding assistant automating the “start work on an issue” workflow for the `OWS-PFMS/elwha` repository. Beyond preparing git state, you **must** clarify requirements, analyze the codebase, and generate a comprehensive implementation plan with rigorous verification criteria. Another agent will execute the plan, and you will later verify completion, so the verification steps you produce must be detailed enough for airtight validation. Never discard user work without explicit confirmation. Stop immediately and report any command errors.

## Context

- **Repository**: `OWS-PFMS/elwha`
- **Default branch**: `main`
- **Project board**: `Material Flat Component Library` (project #5)
- **Branch naming pattern**: `feature/issue-{NUMBER}-{short-description}`
- **Tech stack**: Java 21 + Maven + Swing/FlatLaf (no JUnit test suite yet — see CLAUDE.md)
- **Planning requirement**: Plans must be saved under `docs/stories/issue-{NUMBER}/plan.md` (create directory if needed)
- **Verification requirement**: A separate verification checklist must be saved under `docs/stories/issue-{NUMBER}/verify.md`
- **Multi-agent flow**: You author the plan and verification checklist → a separate agent implements the plan → you verify completion using the checklist

## Usage

/story:start /story:start 6 /story:start issue-6 /story:start FlatPill drag-reorder semantics #42

- If no argument is supplied, list candidate issues (Step 1).
- If an argument is supplied:
  1. Try to resolve it as an exact issue number or `issue-{number}` slug.
  2. If not an exact match, search open issues for close matches to the provided text (title or number fragment).
  3. If one match is found, show a short summary (title + number) and ask the user to confirm before proceeding.
  4. If multiple close matches exist, present the list and ask the user to pick; if none found, fall back to listing all issues as in Step 1.
  5. Continue the workflow once the user confirms the target issue.

## Workflow

### Step 1 – Select Issue
1. If the user supplied an issue argument and it resolved to a single issue, display a brief summary and ask the user to confirm. Continue only after confirmation.
2. If no argument was supplied, or the supplied argument was ambiguous/unresolved:
   - Run: `gh issue list --state open --label enhancement --limit 20`
   - Show the list to the user and ask which issue number to work on. Do not continue until the user responds.

### Step 2 – Fetch Issue Details
1. Run: `gh issue view {ISSUE_NUMBER}`
2. Parse title, labels, milestone, description, acceptance criteria (checkboxes). Store for later display/todo creation.
3. Also fetch issue type and parent/child relationships (needed for Step 2.5 and Step 4):
   ```bash
   gh api graphql -f query='
     query {
       repository(owner:"OWS-PFMS", name:"elwha") {
         issue(number:{ISSUE_NUMBER}) {
           issueType { name }
           parent { number title issueType { name } }
           subIssues(first:50) {
             totalCount
             nodes { number title state }
           }
         }
       }
     }
   '

Store issueType.name, parent (may be null), and subIssues.nodes (will be empty for non-epics; used by Step 2.5 for Epic auto-redirect).

Step 2.5 – Epic Auto-Redirect (re-target to first OPEN child)

1. Skip condition. If issueType.name != "Epic", skip Step 2.5 entirely and proceed to Step 3.
2. Empty-epic refusal (preserved). If subIssues.totalCount == 0, the epic has no children to redirect to. Stop the normal workflow — do NOT create a branch, do NOT touch the project board, do NOT create any docs/stories/ artifacts. Output a refusal:

   ⚠️  Issue #{NUMBER} is an Epic with no children — nothing to redirect to.
   
   Milestone: {milestone title or "None"}
   
   Suggested:
     • Add children first via /story:author:refactor {NUMBER}
     • Or re-type this issue as a regular story
   

   Await user direction before proceeding.
3. No-OPEN-children refusal. If subIssues.totalCount > 0 but every child has state == "CLOSED", also stop the normal workflow with the same hands-off behavior — do NOT create a branch, do NOT touch the project board, do NOT create any docs/stories/ artifacts. Output a refusal listing every (CLOSED) child for context:

   ⚠️  Issue #{NUMBER} is an Epic with no OPEN children — nothing to redirect to.
   
   Milestone: {milestone title or "None"}
   
   Children ({subIssues.totalCount}):
     #{n} CLOSED  {title}
     #{n} CLOSED  {title}
     ...
   

   Await user direction before proceeding.
4. Auto-redirect (the happy path). Iterate subIssues.nodes in the order returned by GraphQL — this is the user-curated order the parent issue was reordered to in the GitHub UI. Do NOT sort by issue number. Pick the first node whose state == "OPEN" (uppercase, matching the GraphQL IssueState enum). Call this {REDIRECT_NUMBER} and {REDIRECT_TITLE}.
5. Print the acknowledgement line, exactly:

   Issue #{NUMBER} is an Epic — auto-starting first OPEN child #{REDIRECT_NUMBER}: {REDIRECT_TITLE}.
   

6. Re-enter the workflow on the child. Set ISSUE_NUMBER := REDIRECT_NUMBER and resume from Step 2 — re-fetch issue details, type, parent, and sub-issues for the redirected child. The Step 1 argument-confirmation prompt is skipped for the redirected target — the redirect line above is the announcement. All subsequent steps (3, 4 including the parent-epic sweep, 5, 6, 7, 8, 9, 10, 11, 12) run against the redirected child unchanged.
7. Nested-epic handling (recursion via re-entry). Because Step 2 is re-run with the redirected number, Step 2.5 fires again whenever the redirected child is itself an Epic. Nested epics therefore walk down to the first OPEN non-Epic descendant via repeated one-hop redirects, with one acknow