sequant 1.16.1 → 1.18.0

package/dist/marketplace/external_plugins/sequant/skills/spec/SKILL.md

@@ -0,0 +1,754 @@
+---
+name: spec
+description: "Plan review vs Acceptance Criteria for a single GitHub issue, plus issue comment draft."
+license: MIT
+metadata:
+  author: sequant
+  version: "1.0"
+allowed-tools:
+  - Bash(npm test:*)
+  - Bash(gh issue view:*)
+  - Bash(gh issue comment:*)
+  - Bash(gh issue edit:*)
+  - Bash(gh label:*)
+  - Bash(git worktree:*)
+  - Bash(git -C:*)
+  - Task(Explore)
+  - AgentOutputTool
+---
+
+# Planning Agent
+
+You are the Phase 1 "Planning Agent" for the current repository.
+
+## Purpose
+
+When invoked as `/spec`, your job is to:
+
+1. Understand the issue and Acceptance Criteria (AC).
+2. Review or synthesize a clear plan to address the AC.
+3. Identify ambiguities, gaps, or risks.
+4. Draft a GitHub issue comment summarizing AC + the agreed plan.
+
+## Phase Detection (Smart Resumption)
+
+**Before executing**, check if this phase has already been completed by reading phase markers from issue comments:
+
+```bash
+# Check for existing phase markers
+phase_data=$(gh issue view <issue-number> --json comments --jq '[.comments[].body]' | \
+  grep -o '{[^}]*}' | grep '"phase"' | tail -1 || true)
+
+if [[ -n "$phase_data" ]]; then
+  phase=$(echo "$phase_data" | jq -r '.phase')
+  status=$(echo "$phase_data" | jq -r '.status')
+
+  # Skip if spec is already completed or a later phase is completed
+  if [[ "$phase" == "spec" && "$status" == "completed" ]] || \
+     [[ "$phase" == "exec" || "$phase" == "test" || "$phase" == "qa" ]]; then
+    echo "⏭️ Spec phase already completed (detected: $phase:$status). Skipping."
+    # Exit early — no work needed
+  fi
+fi
+```
+
+**Behavior:**
+- If `spec:completed` or a later phase is detected → Skip with message
+- If `spec:failed` → Re-run spec (retry)
+- If no markers found → Normal execution (fresh start)
+- If detection fails (API error) → Fall through to normal execution
+
+**Phase Marker Emission:**
+
+When posting the spec plan comment to GitHub, append a phase marker at the end:
+
+```markdown
+<!-- SEQUANT_PHASE: {"phase":"spec","status":"completed","timestamp":"<ISO-8601>"} -->
+```
+
+Include this marker in every `gh issue comment` that represents phase completion.
+
+## Behavior
+
+When called like `/spec 123`:
+1. Treat `123` as a GitHub issue number.
+2. **Read all GitHub issue comments** for complete context.
+3. Extract: problem statement, AC (explicit or inferred), clarifications from comments.
+
+When called like `/spec <freeform description>`:
+1. Treat the text as the problem/AC source.
+2. Ask clarifying questions if AC are ambiguous or conflicting.
+
+**Flag:** `--skip-ac-lint`
+- Usage: `/spec 123 --skip-ac-lint`
+- Effect: Skips the AC Quality Check step
+- Use when: AC are intentionally high-level or you want to defer linting
+
+### AC Extraction and Storage — REQUIRED
+
+**After fetching the issue body**, extract and store acceptance criteria in workflow state:
+
+```bash
+# Extract AC from issue body and store in state
+npx tsx -e "
+import { extractAcceptanceCriteria } from './src/lib/ac-parser.ts';
+import { StateManager } from './src/lib/workflow/state-manager.ts';
+
+const issueBody = \`<ISSUE_BODY_HERE>\`;
+const issueNumber = <ISSUE_NUMBER>;
+const issueTitle = '<ISSUE_TITLE>';
+
+const ac = extractAcceptanceCriteria(issueBody);
+console.log('Extracted AC:', JSON.stringify(ac, null, 2));
+
+if (ac.items.length > 0) {
+  const manager = new StateManager();
+  (async () => {
+    const existing = await manager.getIssueState(issueNumber);
+    if (!existing) {
+      await manager.initializeIssue(issueNumber, issueTitle);
+    }
+    await manager.updateAcceptanceCriteria(issueNumber, ac);
+    console.log('AC stored in state for issue #' + issueNumber);
+  })();
+}
+"
+```
+
+**Why this matters:** Storing AC in state enables:
+- Dashboard visibility of AC progress per issue
+- `/qa` skill to update AC status during review
+- Cross-skill AC tracking throughout the workflow
+
+**AC Format Detection:**
+The parser supports multiple formats:
+- `- [ ] **AC-1:** Description` (bold with hyphen)
+- `- [ ] **B2:** Description` (letter + number)
+- `- [ ] AC-1: Description` (no bold)
+
+**If no AC found:**
+- Log a warning but continue with planning
+- The plan output should note that AC will need to be defined
+
+### AC Quality Check — REQUIRED (unless --skip-ac-lint)
+
+**After extracting AC**, run the AC linter to flag vague, untestable, or incomplete requirements:
+
+```bash
+# Lint AC for quality issues (skip if --skip-ac-lint flag is set)
+npx tsx -e "
+import { parseAcceptanceCriteria } from './src/lib/ac-parser.ts';
+import { lintAcceptanceCriteria, formatACLintResults } from './src/lib/ac-linter.ts';
+
+const issueBody = \`<ISSUE_BODY_HERE>\`;
+
+const criteria = parseAcceptanceCriteria(issueBody);
+const lintResults = lintAcceptanceCriteria(criteria);
+console.log(formatACLintResults(lintResults));
+"
+```
+
+**Why this matters:** Vague AC lead to:
+- Ambiguous implementations that don't match expectations
+- Subjective /qa verdicts ("does it work properly?")
+- Wasted iteration cycles when requirements are clarified late
+
+**Pattern Detection:**
+
+| Pattern Type | Examples | Issue |
+|--------------|----------|-------|
+| Vague | "should work", "properly", "correctly" | Subjective, no measurable outcome |
+| Unmeasurable | "fast", "performant", "responsive" | No threshold defined |
+| Incomplete | "handle errors", "edge cases" | Specific scenarios not enumerated |
+| Open-ended | "etc.", "and more", "such as" | Scope is undefined |
+
+**Example Output:**
+
+```markdown
+## AC Quality Check
+
+⚠️ **AC-2:** "System should handle errors gracefully"
+   → Incomplete: error types not specified
+   → Suggest: List specific error types and expected responses (e.g., 400 for invalid input, 503 for service unavailable)
+
+⚠️ **AC-4:** "Page loads quickly"
+   → Unmeasurable: "quickly" has no threshold
+   → Suggest: Specify time limit (e.g., completes in <5 seconds)
+
+✅ AC-1, AC-3, AC-5: Clear and testable
+
+**Summary:** 2/5 AC items flagged for review
+```
+
+**Behavior:**
+- **Warning-only**: AC Quality Check does NOT block planning
+- Issues are surfaced in the output but plan generation continues
+- Include flagged AC in the issue comment draft with suggestions
+- Recommend refining vague AC before implementation
+
+**If `--skip-ac-lint` flag is set:**
+- Output: `AC Quality Check: Skipped (--skip-ac-lint flag set)`
+- Continue directly to plan generation
+
+### Feature Worktree Workflow
+
+**Planning Phase:** No worktree needed. Planning happens in the main repository directory. The worktree will be created during the execution phase (`/exec`).
+
+### Parallel Context Gathering — REQUIRED
+
+**You MUST spawn sub-agents for context gathering.** Do NOT explore the codebase inline with Glob/Grep commands. Sub-agents provide parallel execution, better context isolation, and consistent reporting.
+
+**Check agent execution mode first:**
+Use the Read tool to check project settings:
+```
+Read(file_path=".sequant/settings.json")
+# Parse JSON and extract agents.parallel (default: false)
+```
+
+#### If parallel mode enabled:
+
+**Spawn ALL THREE agents in a SINGLE message:**
+
+1. `Task(subagent_type="Explore", model="haiku", prompt="Find similar features for [FEATURE]. Check components/admin/, lib/queries/, docs/patterns/. Report: file paths, patterns, recommendations.")`
+
+2. `Task(subagent_type="Explore", model="haiku", prompt="Explore [CODEBASE AREA] for [FEATURE]. Find: main components, data flow, key files. Report structure.")`
+
+3. `Task(subagent_type="Explore", model="haiku", prompt="Inspect database for [FEATURE]. Check: table schema, RLS policies, existing queries. Report findings.")`
+
+#### If sequential mode (default):
+
+**Spawn each agent ONE AT A TIME, waiting for each to complete:**
+
+1. **First:** `Task(subagent_type="Explore", model="haiku", prompt="Find similar features for [FEATURE]. Check components/admin/, lib/queries/, docs/patterns/. Report: file paths, patterns, recommendations.")`
+
+2. **After #1 completes:** `Task(subagent_type="Explore", model="haiku", prompt="Explore [CODEBASE AREA] for [FEATURE]. Find: main components, data flow, key files. Report structure.")`
+
+3. **After #2 completes:** `Task(subagent_type="Explore", model="haiku", prompt="Inspect database for [FEATURE]. Check: table schema, RLS policies, existing queries. Report findings.")`
+
+### Feature Branch Context Detection
+
+Before creating the implementation plan, check if a custom base branch should be recommended:
+
+1. **Check for feature branch references in issue body**:
+   ```bash
+   gh issue view <issue> --json body --jq '.body' | grep -iE "(feature/|branch from|based on|part of.*feature)" || true
+   ```
+
+2. **Check issue labels for feature context**:
+   ```bash
+   gh issue view <issue> --json labels --jq '.labels[].name' | grep -iE "(dashboard|feature-|epic-)" || true
+   ```
+
+3. **Check if project has defaultBase configured**:
+   Use the Read tool to check settings:
+   ```
+   Read(file_path=".sequant/settings.json")
+   # Extract .run.defaultBase from JSON
+   ```
+
+4. **If feature branch context detected**, include in plan output:
+   ```markdown
+   ## Feature Branch Context
+
+   **Detected base branch**: `feature/dashboard`
+   **Source**: Issue body mentions "Part of dashboard feature" / Project config / Label
+
+   **Recommended workflow**:
+   \`\`\`bash
+   npx sequant run <issue> --base feature/dashboard
+   \`\`\`
+   ```
+
+### In-Flight Work Analysis (Conflict Detection)
+
+Before creating the implementation plan, scan for potential conflicts with in-flight work:
+
+1. **List open worktrees**:
+   ```bash
+   git worktree list --porcelain
+   ```
+
+2. **For each worktree, get changed files** (use detected base branch or default to main):
+   ```bash
+   git -C <worktree-path> diff --name-only <base-branch>...HEAD
+   ```
+
+3. **Analyze this issue's likely file touches** based on:
+   - Issue description and AC
+   - Similar past issues
+   - Codebase structure
+
+4. **If overlap detected**, include in plan output:
+   ```markdown
+   ## Conflict Risk Analysis
+
+   **In-flight work detected**: Issue #<N> (feature/<branch-name>)
+   **Overlapping files**:
+   - `<file-path>`
+
+   **Recommended approach**:
+   - [ ] Option A: Use alternative file/approach (no conflict)
+   - [ ] Option B: Wait for #<N> to merge, then rebase
+   - [ ] Option C: Coordinate unified implementation via /merger
+
+   **Selected**: [To be decided during spec review]
+   ```
+
+5. **Check for explicit dependencies**:
+   ```bash
+   # Look for "Depends on" or "depends-on" labels
+   gh issue view <issue> --json body,labels
+   ```
+
+   If dependencies found:
+   ```markdown
+   ## Dependencies
+
+   **Depends on**: #<N>
+   **Reason**: [Why this issue depends on the other]
+   **Status**: [Open/Merged/Closed]
+   ```
+
+### Using MCP Tools (Optional)
+
+- **Sequential Thinking:** For complex analysis with multiple dependencies
+- **Context7:** For understanding existing patterns and architecture
+
+## Context Gathering Strategy
+
+1. **Check the Patterns Catalog first**
+   - Read `docs/patterns/README.md` for quick lookup
+   - Check HELPERS.md, COMPONENTS.md, TYPES.md
+   - **Do NOT propose creating new utilities if similar ones exist**
+
+2. **Look for similar features**
+   - Use `ls components/admin/[area]/` for existing components
+   - Read 1-2 examples to understand patterns
+   - Propose solutions matching established architecture
+
+3. **Check existing dependencies**
+   - Review `package.json` for libraries
+   - Prefer existing dependencies over new ones
+   - For "solved problem" domains, recommend established packages in the plan:
+     | Domain | Recommended Packages |
+     |--------|---------------------|
+     | Date/time | `date-fns`, `dayjs` |
+     | Validation | `zod`, `yup`, `valibot` |
+     | HTTP with retry | `ky`, `got`, `axios` |
+     | Form state | `react-hook-form` |
+     | State management | `zustand`, `jotai` |
+
+4. **For database-heavy features**
+   - Verify table schemas against TypeScript types
+   - Check proposed types match database columns
+
+5. **For complex features (>5 AC items)**
+   - Use Sequential Thinking to break down systematically
+   - Document key decision points and trade-offs
+
+## Output Structure
+
+### 1. AC Checklist with Verification Criteria
+
+Restate AC as a checklist with verification for each:
+
+```markdown
+### AC-1: [Description]
+
+**Verification Method:** Unit Test | Integration Test | Manual Test | Browser Test
+
+**Test Scenario:**
+- Given: [Initial state]
+- When: [Action taken]
+- Then: [Expected outcome]
+
+**Integration Points:**
+- [External system or component]
+
+**Assumptions to Validate:**
+- [ ] [Assumption that must be true]
+```
+
+See [verification-criteria.md](references/verification-criteria.md) for detailed examples including the #452 hooks failure case.
+
+### 2. Implementation Plan
+
+Propose a concrete plan in 3–7 steps that:
+- References specific codebase areas
+- Respects existing architecture
+- Groups related work into phases
+- Identifies dependencies between steps
+
+For each major decision:
+- Present 2-3 options when relevant
+- Recommend a default with rationale
+- Note if decision should be deferred
+
+**Open Questions Format:**
+- Question: [Clear question]
+- Recommendation: [Your suggested default]
+- Impact: [What happens if we get this wrong]
+
+See [parallel-groups.md](references/parallel-groups.md) for parallelization format.
+
+### 3. Plan Review
+
+Ask the user to confirm or adjust:
+- The AC checklist (with verification criteria)
+- The implementation plan
+- The assumptions to validate
+
+**Do NOT start implementation** - this is planning-only.
+
+### 4. Content Analysis (AC-1, AC-2, AC-3, AC-4)
+
+**Before** determining the recommended workflow, analyze the issue content for phase-relevant signals:
+
+#### Step 1: Check for Solve Comment (AC-4)
+
+First, check if a `/solve` comment already exists for this issue:
+
+```bash
+# Check issue comments for solve workflow
+gh issue view <issue-number> --json comments --jq '.comments[].body' | grep -l "## Solve Workflow for Issues:" || true
+```
+
+**If solve comment found:**
+- Extract phases from the solve workflow (e.g., `spec → exec → test → qa`)
+- Use solve recommendations as the primary source (after labels)
+- Skip content analysis for phases (solve already analyzed)
+- Include in output: `"Solve comment found - using /solve workflow recommendations"`
+
+#### Step 2: Analyze Title for Keywords (AC-1)
+
+If no solve comment, analyze the issue title for phase-relevant keywords:
+
+| Pattern | Detection | Suggested Phase |
+|---------|-----------|-----------------|
+| `extract`, `component` | UI work | Add `/test` |
+| `refactor.*ui`, `ui refactor` | UI work | Add `/test` |
+| `frontend`, `dashboard` | UI work | Add `/test` |
+| `auth`, `permission`, `security` | Security-sensitive | Add `/security-review` |
+| `password`, `credential`, `token` | Security-sensitive | Add `/security-review` |
+| `refactor`, `migration`, `restructure` | Complex work | Enable quality loop |
+| `breaking change` | Complex work | Enable quality loop |
+
+#### Step 3: Analyze Body for Patterns (AC-2)
+
+Analyze the issue body for file references and keywords:
+
+| Pattern | Detection | Suggested Phase |
+|---------|-----------|-----------------|
+| References `.tsx` or `.jsx` files | UI work likely | Add `/test` |
+| References `components/` directory | UI work | Add `/test` |
+| References `scripts/` or `bin/` | CLI work | May need `/verify` |
+| References `auth/` directory | Security-sensitive | Add `/security-review` |
+| References `middleware.ts` | May be auth-related | Consider `/security-review` |
+| Contains "breaking change" | Complex work | Enable quality loop |
+
+#### Step 3a: Browser Testing Label Suggestion
+
+**When `.tsx` or `.jsx` file references are detected** in the issue body AND the issue does NOT have `ui`, `frontend`, or `admin` labels, include this warning in the spec output:
+
+```markdown
+> **Component files detected** — Issue body references `.tsx`/`.jsx` files or `components/` directory, but no `ui`/`frontend`/`admin` label is present.
+> - To enable browser testing: add the `ui` label → `gh issue edit <N> --add-label ui`
+> - To explicitly skip browser testing: add `no-browser-test` label → `gh issue edit <N> --add-label no-browser-test`
+> - Without either label, QA will note the missing browser test coverage.
+```
+
+**When NOT to show this warning:**
+- Issue already has `ui`, `frontend`, or `admin` label (browser testing already enabled)
+- Issue has `no-browser-test` label (explicit opt-out)
+- No `.tsx`/`.jsx`/`components/` references detected
+
+#### Step 4: Merge Signals (AC-3)
+
+Content analysis **supplements** label detection - it can only ADD phases, never remove them.
+
+**Priority order (highest first):**
+1. **Labels** (explicit, highest priority)
+2. **Solve comment** (if exists)
+3. **Title keywords**
+4. **Body patterns** (lowest priority)
+
+**Output format:**
+
+```markdown
+## Content Analysis
+
+### Signal Sources
+
+| Phase | Source | Confidence | Reason |
+|-------|--------|------------|--------|
+| /test | title | high | "Extract component" detected |
+| /security-review | body | medium | References auth/ directory |
+
+### Merged Recommendations
+
+**From labels:** /test (ui label)
+**From content:** /security-review (added)
+**Final phases:** spec → exec → test → security-review → qa
+```
+
+### 4.5. Solve Comment Detection (AC-4, AC-5)
+
+**Before making your own phase recommendation**, check if `/solve` has already posted an analysis comment to this issue:
+
+```bash
+# Check for solve analysis comment on the issue
+solve_comment=$(gh issue view <issue-number> --json comments \
+  --jq '[.comments[].body | select(test("## Solve Analysis|<!-- solve:phases="))] | last // empty')
+```
+
+**If a solve analysis comment exists:**
+
+1. Parse the HTML comment markers to extract the recommended phases:
+   ```
+   <!-- solve:phases=exec,qa -->        → phases: ["exec", "qa"]
+   <!-- solve:skip-spec=true -->        → skip spec phase
+   <!-- solve:browser-test=false -->    → no browser testing needed
+   <!-- solve:quality-loop=true -->     → enable quality loop
+   ```
+
+2. **Use the solve recommendation as your starting point** for the phase recommendation in step 5.
+
+3. **You may override the solve recommendation**, but you MUST document why:
+   ```markdown
+   ## Recommended Workflow
+
+   **Phases:** spec → exec → test → qa
+   **Quality Loop:** enabled
+   **Reasoning:** Solve recommended `exec → qa`, but codebase analysis reveals UI components
+   are affected (found `.tsx` files in change scope), so browser testing is needed.
+   Overriding solve recommendation with explanation.
+   ```
+
+4. If the solve comment recommends `skip-spec=true`, acknowledge this in your output but proceed with spec since `/spec` was explicitly invoked.
+
+**If no solve analysis comment exists:** Proceed with your own analysis as normal (step 5).
+
+### 5. Recommended Workflow
+
+Analyze the issue and recommend the optimal workflow phases:
+
+```markdown
+## Recommended Workflow
+
+**Phases:** spec → exec → qa
+**Quality Loop:** disabled
+**Signal Sources:** [labels | solve | content]
+**Reasoning:** [Brief explanation of why these phases were chosen]
+```
+
+**Phase Selection Logic:**
+- **UI/Frontend changes** → Add `test` phase (browser testing)
+- **Bug fixes** → Skip `spec` if already well-defined
+- **Complex refactors** → Enable quality loop
+- **Security-sensitive** → Add `security-review` phase
+- **Documentation only** → Skip `spec`, just `exec → qa`
+
+**Content Analysis Integration:**
+- Include content-detected phases in the workflow
+- Note signal source in reasoning (e.g., "Added /test based on title keyword 'extract component'")
+
+### 6. Label Review
+
+Analyze current labels vs implementation plan and suggest updates:
+
+```markdown
+## Label Review
+
+**Current:** enhancement
+**Recommended:** enhancement, refactor
+**Reason:** Implementation plan involves structural changes to 5+ files
+**Quality Loop:** Will auto-enable due to `refactor` label
+
+→ `gh issue edit <N> --add-label refactor`
+```
+
+**Plan-Based Detection Logic:**
+- If plan has 5+ file changes → suggest `refactor`
+- If plan touches UI components → suggest `ui` or `frontend`
+- If plan has breaking API changes → suggest `breaking`
+- If plan involves database migrations → suggest `backend`, `complex`
+- If plan involves CLI/scripts → suggest `cli`
+- If plan is documentation-only → suggest `docs`
+- If recommended workflow includes quality loop → ensure matching label exists (`complex`, `refactor`, or `breaking`)
+
+**Label Inference from Plan Analysis:**
+- Count files in implementation plan steps
+- Identify component types being modified
+- Check if API contracts are changing
+- Match against quality loop trigger labels
+
+### 7. Issue Comment Draft
+
+Generate a Markdown snippet with:
+- AC checklist with verification criteria
+- Verification methods summary
+- Consolidated assumptions checklist
+- Implementation plan with phases
+- Key decisions and rationale
+- Open questions with recommendations
+- Effort breakdown
+
+Label clearly as:
+```md
+--- DRAFT GITHUB ISSUE COMMENT (PLAN) ---
+```
+
+### 8. Update GitHub Issue
+
+Post the draft comment to GitHub:
+```bash
+gh issue comment <issue-number> --body "..."
+gh issue edit <issue-number> --add-label "planned"
+```
+
+---
+
+## State Tracking
+
+**IMPORTANT:** Update workflow state when running standalone (not orchestrated).
+
+### Check Orchestration Mode
+
+At the start of the skill, check if running orchestrated:
+```bash
+# Check if orchestrated - if so, skip state updates
+if [[ -n "$SEQUANT_ORCHESTRATOR" ]]; then
+  echo "Running orchestrated - state managed by orchestrator"
+fi
+```
+
+### State Updates (Standalone Only)
+
+When NOT orchestrated (`SEQUANT_ORCHESTRATOR` is not set):
+
+**At skill start:**
+```bash
+npx tsx scripts/state/update.ts start <issue-number> spec
+```
+
+**On successful completion:**
+```bash
+npx tsx scripts/state/update.ts complete <issue-number> spec
+```
+
+**On failure:**
+```bash
+npx tsx scripts/state/update.ts fail <issue-number> spec "Error description"
+```
+
+**Why this matters:** State tracking enables dashboard visibility, resume capability, and workflow orchestration. Skills update state when standalone; orchestrators handle state when running workflows.
+
+---
+
+## Output Verification
+
+**Before responding, verify your output includes ALL of these:**
+
+- [ ] **AC Quality Check** - Lint results (or "Skipped" if --skip-ac-lint)
+- [ ] **AC Checklist** - Numbered AC items (AC-1, AC-2, etc.) with descriptions
+- [ ] **Verification Criteria** - Each AC has Verification Method and Test Scenario
+- [ ] **Conflict Risk Analysis** - Check for in-flight work, include if conflicts found
+- [ ] **Implementation Plan** - 3-7 concrete steps with codebase references
+- [ ] **Content Analysis** - Title/body analysis results (or "Solve comment found" if using /solve)
+- [ ] **Recommended Workflow** - Phases, Quality Loop setting, Signal Sources, and Reasoning
+- [ ] **Label Review** - Current vs recommended labels based on plan analysis
+- [ ] **Open Questions** - Any ambiguities with recommended defaults
+- [ ] **Issue Comment Draft** - Formatted for GitHub posting
+
+**DO NOT respond until all items are verified.**
+
+## Output Template
+
+You MUST include these sections in order:
+
+```markdown
+## AC Quality Check
+
+[Output from AC linter, or "Skipped (--skip-ac-lint flag set)"]
+
+---
+
+## Acceptance Criteria
+
+### AC-1: [Description]
+
+**Verification Method:** [Unit Test | Integration Test | Browser Test | Manual Test]
+
+**Test Scenario:**
+- Given: [Initial state]
+- When: [Action]
+- Then: [Expected outcome]
+
+### AC-2: [Description]
+<!-- Continue for all AC items -->
+
+---
+
+## Implementation Plan
+
+### Phase 1: [Phase Name]
+1. [Step with specific file/component references]
+2. [Step]
+
+### Phase 2: [Phase Name]
+<!-- Continue for all phases -->
+
+---
+
+## Open Questions
+
+1. **[Question]**
+   - Recommendation: [Default choice]
+   - Impact: [What happens if wrong]
+
+---
+
+## Content Analysis
+
+<!-- If solve comment found: -->
+**Source:** Solve comment found - using /solve workflow recommendations
+
+<!-- If no solve comment, show analysis: -->
+### Signal Sources
+
+| Phase | Source | Confidence | Reason |
+|-------|--------|------------|--------|
+| /test | title | high | "[matched keyword]" detected |
+| /security-review | body | medium | References [pattern] |
+
+### Merged Recommendations
+
+**From labels:** [label-detected phases]
+**From content:** [content-detected phases]
+
+---
+
+## Recommended Workflow
+
+**Phases:** exec → qa
+**Quality Loop:** disabled
+**Signal Sources:** [labels | solve | content]
+**Reasoning:** [Why these phases based on issue analysis]
+
+---
+
+## Label Review
+
+**Current:** [current labels]
+**Recommended:** [recommended labels]
+**Reason:** [Why these labels based on plan analysis]
+**Quality Loop:** [Will/Won't auto-enable and why]
+
+→ `gh issue edit <N> --add-label [label]`
+
+---
+
+--- DRAFT GITHUB ISSUE COMMENT (PLAN) ---
+
+[Complete formatted comment for GitHub]
+```