Squad Refine

> Shared context: read `../squad/shared.md` for pipeline levels, status transitions, API endpoints, error handling, and agent context flow.
> Safety principles: read `../squad/principles.md` — **mandatory, not optional.**

## `/squad-refine <ID>` — Refine Backlog Requirements

Reads a rough backlog item and refines it into concrete, actionable requirements through structured user interview.

**Target**: tasks in `todo` status (backlog). If the task is not `todo`, warn the user and confirm before proceeding.

### Procedure

```
① Read the task
   TASK = curl GET /api/task/$ID?project=$PROJECT
   Extract: title, description, priority, level, tags

① ½. Look for prior implementation context (always run this before the interview)

   a. Check description and tags for dependency hints:
      - "Depends on: #NNN" lines in description
      - Tags like "after:NNN", "follows:NNN"

   b. If dependency found → fetch that card's implementation output:
      PRIOR = curl GET /api/task/$NNN?project=$PROJECT&fields=title,implementation_notes,plan
      Also inspect the actual codebase: read files, interfaces, schemas confirmed in that card.

   c. If no explicit dependency → ask ONE question before the main interview:
      "Is there a prior task whose implementation this builds on? (task ID or 'none')"
      If the user gives an ID, fetch it as in (b).
      If "none" or new work → skip, proceed with regular interview.

   d. Summarize what was confirmed from prior implementation:
      PRIOR_CONTEXT = {
        confirmed interfaces, schemas, file paths, component names, API routes, etc.
      }
      This context is injected into ③ (gap analysis) and ⑤ (description synthesis).

② Display current state
   Show the user their raw title + description as-is.
   If PRIOR_CONTEXT exists, also show: "Prior implementation context: [summary]"

③ Analyze for gaps
   Identify what's missing or vague across these dimensions:
   - WHAT: What exactly should be built/changed?
   - WHY: What problem does this solve? What's the motivation?
   - SCOPE: What's included vs excluded?
   - ACCEPTANCE: How do we know it's done?
   - CONSTRAINTS: Technical limitations, compatibility, performance?
   - EDGE CASES: Error states, boundary conditions?
   - DEPENDENCIES: Does it depend on other tasks or external systems?

④ Interview the user (MANDATORY)
   Use AskUserQuestion to ask about the gaps found in ③.
   Rules:
   - Ask 1–4 focused questions per round (AskUserQuestion limit)
   - Group related questions in one round
   - Run multiple rounds if needed (max 3 rounds)
   - Stop early if the user says "enough" or all gaps are filled
   - Don't ask about things that are already clear
   - Use concrete options when possible, not open-ended questions

⑤ Synthesize refined description
   Rewrite the description using this template.
   If PRIOR_CONTEXT exists, ground scope/requirements/constraints in confirmed interfaces
   and file paths from the prior implementation — not assumptions.

   ## Goal
   [1–2 sentences: what this task achieves and why]

   ## Prior Implementation Context  ← include only if PRIOR_CONTEXT exists
   [Confirmed interfaces, schemas, components, or file paths from the prior card
    that this task directly builds on. e.g. "POST /api/items → {id, name} per #201"]

   ## Scope
   - IN: [bulleted list of what's included]
   - OUT: [bulleted list of what's explicitly excluded]

   ## Requirements
   [Numbered list of concrete, testable requirements]

   ## Acceptance Criteria
   - [ ] [Checklist items — each verifiable]

   ## Constraints
   [Technical constraints, if any identified]

   ## Edge Cases
   [Edge cases to handle, if any identified]

   Omit sections that have no content (e.g., skip Constraints if