sequant 2.1.2 → 2.3.0

package/templates/skills/spec/SKILL.md

@@ -4,7 +4,7 @@ description: "Plan review vs Acceptance Criteria for a single GitHub issue, plus
 license: MIT
 metadata:
   author: sequant
-  version: "1.0"
+  version: "2.1"
 allowed-tools:
   - Bash(npm test:*)
   - Bash(gh issue view:*)
@@ -19,987 +19,212 @@ allowed-tools:
 
 # Planning Agent
 
-You are the Phase 1 "Planning Agent" for the current repository.
+Phase 1 "Planning Agent." Understands the issue and AC, reviews or synthesizes a plan, identifies gaps and risks, and drafts a GitHub issue comment.
 
-## Purpose
+## Platform Detection — Run First
 
-When invoked as `/spec`, your job is to:
+```bash
+gh --version >/dev/null 2>&1 && GITHUB_AVAILABLE=true || GITHUB_AVAILABLE=false
+SETTINGS_AVAILABLE=false; [ -f ".sequant/settings.json" ] && SETTINGS_AVAILABLE=true
+```
 
-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.
+- **GitHub unavailable:** Skip phase detection, label review, auto-comment. Prompt user for AC from description text.
+- **Settings unavailable:** Use defaults silently (sequential agents, no custom scope config).
 
-## Phase Detection (Smart Resumption)
+## Phase Detection
 
-**Before executing**, check if this phase has already been completed by reading phase markers from issue comments:
+If GitHub is available, check for prior phase completion:
 
 ```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:
+- `spec:completed` or later phase detected → Skip with message
+- `spec:failed` → Re-run
+- No markers / API error → Normal execution
 
-```markdown
+Append to every phase-completion comment:
+```
 <!-- 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.
+**`/spec 123`** — GitHub issue number. Read all comments for full context. Extract AC.
+**`/spec <text>`** — Freeform problem/AC source. Ask clarifying questions if ambiguous.
 
-**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
+**Flags:** `--skip-ac-lint` (skip AC quality check), `--skip-scope-check` (skip scope assessment).
 
-**Flag:** `--skip-scope-check`
-- Usage: `/spec 123 --skip-scope-check`
-- Effect: Skips the Scope Assessment step
-- Use when: Issue scope is intentionally complex or you want to defer assessment
+## Complexity Tier Determination
 
-### AC Extraction and Storage — REQUIRED
+Determine the output tier **before** generating any output. Announce it as the first line.
 
-**After fetching the issue body**, extract and store acceptance criteria in workflow state:
+| Tier | Criteria | Output Scope | Target |
+|------|----------|--------------|--------|
+| **Simple** | `simple-fix`/`typo`/`docs-only` label, or `bug` with ≤2 AC | AC list + plan + Design Review Q1/Q3 only | <4,000 chars |
+| **Standard** | 3–8 AC, no complexity labels | Full output minus Polish, minus trivially-passing quality checks | <8,000 chars |
+| **Complex** | `complex`/`refactor`/`breaking` label, or 9+ AC | Full output including all quality dimensions | <15,000 chars |
 
-```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);
-  })();
-}
-"
-```
+First line of output: `**Complexity: [Tier]** ([N] ACs, [N] directories)`
 
-**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
+Mark tier in HTML comment for downstream parsing: `<!-- SEQUANT_SPEC_TIER: [tier] -->`
 
-**AC Format Detection:**
-The parser supports multiple formats:
-- `- [ ] **AC-1:** Description` (bold with hyphen)
-- `- [ ] **B2:** Description` (letter + number)
-- `- [ ] AC-1: Description` (no bold)
+## Programmatic Checks (Conditional)
 
-**If no AC found:**
-- Log a warning but continue with planning
-- The plan output should note that AC will need to be defined
+**Guard:** Only run `npx tsx` blocks if `./src/lib/ac-parser.ts` exists (sequant repo). Otherwise, perform all analysis inline by reading the issue text directly.
 
-### AC Quality Check — REQUIRED (unless --skip-ac-lint)
+### If guard passes:
 
-**After extracting AC**, run the AC linter to flag vague, untestable, or incomplete requirements:
+1. **AC Extraction & Storage:** Use `extractAcceptanceCriteria` from `./src/lib/ac-parser.ts` and `StateManager` from `./src/lib/workflow/state-manager.ts` to parse and store AC in `.sequant/state.json`. Supports formats: `- [ ] **AC-1:** Desc`, `- [ ] AC-1: Desc`, `- [ ] **B2:** Desc`.
 
-```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';
+2. **AC Quality Check** (unless `--skip-ac-lint`): Use `lintAcceptanceCriteria` from `./src/lib/ac-linter.ts`. Warning-only — does not block planning. Flag these patterns:
 
-const issueBody = \`<ISSUE_BODY_HERE>\`;
-
-const criteria = parseAcceptanceCriteria(issueBody);
-const lintResults = lintAcceptanceCriteria(criteria);
-console.log(formatACLintResults(lintResults));
-"
-```
+   | Pattern | Examples | Issue |
+   |---------|----------|-------|
+   | Vague | "should work", "properly" | No measurable outcome |
+   | Unmeasurable | "fast", "performant" | No threshold defined |
+   | Incomplete | "handle errors", "edge cases" | Scenarios not enumerated |
+   | Open-ended | "etc.", "and more" | Scope undefined |
+   | Title/body tension | doc-noun title ("note", "comment", "snippet") + runtime-imperative body ("execute", "trigger", "capture", incl. inflections like `triggered`/`captured`, `run /<cmd>`); separators `.`/`\n`/`:`/`—` | Two different verification bars |
 
-**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
+3. **Scope Assessment** (unless `--skip-scope-check`): Use `performScopeAssessment` from `./src/lib/scope/index.ts` with settings from `getSettings()`. Verdicts: SCOPE_OK (green), SCOPE_WARNING (yellow, auto-enables quality loop), SCOPE_SPLIT_RECOMMENDED (red). Store results in state.
 
-**Pattern Detection:**
+### If guard fails (consumer projects):
 
-| 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
+Perform the same analysis inline:
+- Extract AC by pattern-matching the issue body
+- Flag vague/unmeasurable AC in the AC Quality Check section
+- Assess scope using the same green/yellow/red heuristics on feature count, AC count, directory spread
 
-⚠️ **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)
+## Context Gathering
 
-⚠️ **AC-4:** "Page loads quickly"
-   → Unmeasurable: "quickly" has no threshold
-   → Suggest: Specify time limit (e.g., completes in <5 seconds)
+### Discover Project Structure — REQUIRED
 
-✅ 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
-
-### Scope Assessment — REQUIRED (unless --skip-scope-check)
-
-**After AC Quality Check**, run scope assessment to detect overscoped issues:
+**Do NOT use hardcoded paths.** Discover what actually exists:
 
 ```bash
-# Run scope assessment (skip if --skip-scope-check flag is set)
-npx tsx -e "
-import { parseAcceptanceCriteria } from './src/lib/ac-parser.ts';
-import { performScopeAssessment, formatScopeAssessment, convertSettingsToConfig } from './src/lib/scope/index.ts';
-import { getSettings } from './src/lib/settings.ts';
-
-const issueBody = \`<ISSUE_BODY_HERE>\`;
-const issueTitle = '<ISSUE_TITLE>';
-
-(async () => {
-  const settings = await getSettings();
-  const config = convertSettingsToConfig(settings.scopeAssessment);
-
-  const criteria = parseAcceptanceCriteria(issueBody);
-  const assessment = performScopeAssessment(criteria, issueBody, issueTitle, config);
-  console.log(formatScopeAssessment(assessment));
-})();
-"
+ls -d src/ app/ lib/ components/ pages/ routes/ docs/ 2>/dev/null || true
 ```
 
-**Why this matters:**
-- Bundled features (3+ distinct features) should be separate issues
-- Missing non-goals lead to scope creep during implementation
-- High AC counts increase complexity and error rates
-
-**Scope Metrics:**
-
-| Metric | Green | Yellow | Red |
-|--------|-------|--------|-----|
-| Feature count | 1 | 2 | 3+ |
-| AC items | 1-5 | 6-8 | 9+ |
-| Directory spread | 1-2 | 3-4 | 5+ |
+Use discovered paths in all agent prompts and search commands.
 
-**Non-Goals Section:**
+### Agent Spawn Rules
 
-Every `/spec` output MUST include a Non-Goals section. If the issue lacks one, output a warning:
+Determine agent count from issue content — do NOT always spawn 3:
 
-```markdown
-## Non-Goals
-
-⚠️ **Non-Goals section not found.** Consider adding scope boundaries.
-
-Example format:
-- [ ] [Adjacent feature we're deferring]
-- [ ] [Scope boundary we're respecting]
-- [ ] [Future work that's out of scope]
-```
+| Issue Content | Agents | What to Spawn |
+|---------------|--------|---------------|
+| Database/SQL/migration keywords in AC or labels | 3 | Similar features + Codebase area + Database schema |
+| UI/frontend (`.tsx`/`.jsx`/`components/` references) | 2 | Similar features + Codebase area |
+| CLI/script changes | 2 | Similar features + Codebase area |
+| Docs/config/`simple-fix` label | 1 | General context only |
 
-**Scope Verdicts:**
+**Execution mode:** Read `.sequant/settings.json` → `agents.parallel` (default: false).
+- **Parallel:** Spawn all agents in a SINGLE message
+- **Sequential:** Spawn one at a time, waiting for each to complete
 
-| Verdict | Meaning | Action |
-|---------|---------|--------|
-| ✅ SCOPE_OK | Single focused feature | Proceed normally |
-| ⚠️ SCOPE_WARNING | Moderate complexity | Consider narrowing; quality loop auto-enabled |
-| ❌ SCOPE_SPLIT_RECOMMENDED | Multiple features bundled | Strongly recommend splitting |
+Agent prompts MUST reference discovered paths from the step above, not hardcoded ones like `components/admin/` or `lib/queries/`.
 
-**Quality Loop Auto-Enable:**
+### In-Flight Work Analysis
 
-If scope verdict is SCOPE_WARNING or SCOPE_SPLIT_RECOMMENDED:
-- Quality loop is automatically enabled
-- Include note in Recommended Workflow section:
-  ```markdown
-  **Quality Loop:** enabled (auto-enabled due to scope concerns)
-  ```
-
-**If `--skip-scope-check` flag is set:**
-- Output: `Scope Assessment: Skipped (--skip-scope-check flag set)`
-- Continue to plan generation
-
-**Store in State:**
-
-After assessment, store results in workflow state for analytics:
+Scan for potential conflicts before planning:
 
 ```bash
-npx tsx -e "
-import { StateManager } from './src/lib/workflow/state-manager.ts';
-import { performScopeAssessment, convertSettingsToConfig } from './src/lib/scope/index.ts';
-import { getSettings } from './src/lib/settings.ts';
-
-(async () => {
-  const settings = await getSettings();
-  const config = convertSettingsToConfig(settings.scopeAssessment);
-
-  // ... perform assessment with config ...
-  // const assessment = performScopeAssessment(criteria, issueBody, issueTitle, config);
-
-  const manager = new StateManager();
-  await manager.updateScopeAssessment(issueNumber, assessment);
-})();
-"
+git worktree list --porcelain
+# For each worktree: git -C <path> diff --name-only origin/main...HEAD
 ```
 
-### 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. `Agent(subagent_type="sequant-explorer", prompt="Find similar features for [FEATURE]. Check components/admin/, lib/queries/, docs/patterns/. Report: file paths, patterns, recommendations.")`
-
-2. `Agent(subagent_type="sequant-explorer", prompt="Explore [CODEBASE AREA] for [FEATURE]. Find: main components, data flow, key files. Report structure.")`
-
-3. `Agent(subagent_type="sequant-explorer", 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:** `Agent(subagent_type="sequant-explorer", prompt="Find similar features for [FEATURE]. Check components/admin/, lib/queries/, docs/patterns/. Report: file paths, patterns, recommendations.")`
-
-2. **After #1 completes:** `Agent(subagent_type="sequant-explorer", prompt="Explore [CODEBASE AREA] for [FEATURE]. Find: main components, data flow, key files. Report structure.")`
-
-3. **After #2 completes:** `Agent(subagent_type="sequant-explorer", 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:
+If overlap detected → include **Conflict Risk Analysis** section with options (alternative approach / wait for merge / coordinate via /merger).
 
-1. **List open worktrees**:
-   ```bash
-   git worktree list --porcelain
-   ```
+Check for explicit dependencies: `gh issue view <issue> --json body,labels`. If "Depends on" found → include **Dependencies** section with status.
 
-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
-   ```
+### Feature Branch Context
 
-3. **Analyze this issue's likely file touches** based on:
-   - Issue description and AC
-   - Similar past issues
-   - Codebase structure
+Check issue body/labels for feature branch references (`feature/`, `based on`, epic labels). If found, recommend `--base feature/<branch>` in the plan.
 
-4. **If overlap detected**, include in plan output:
-   ```markdown
-   ## Conflict Risk Analysis
+### Sibling-site Scan (Conditional)
 
-   **In-flight work detected**: Issue #<N> (feature/<branch-name>)
-   **Overlapping files**:
-   - `<file-path>`
+**When to apply:** Focused AC + a localized fix where the same root-cause pattern likely exists at sibling sites in the same file (≥3 instances of the affected pattern in the same file — e.g. the regex blocks in `pre-tool.sh`).
 
-   **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
+**During planning**, scan the same file/module for sibling code matching the bug's root cause. If sibling sites are found, surface them as either: **(a)** an Open Question (in `## Open Questions`) proposing scope expansion (only when trivially co-located), or **(b)** a recommended follow-up issue (in `## Implementation Plan` or as a separate plan step). When findings mix trivial and non-trivial sites, surface each separately. **Don't silently widen scope — the user decides.**
 
-   **Selected**: [To be decided during spec review]
-   ```
+This operationalizes the principle in `feedback_qa_second_look.md` (structured analysis biases positive on the literal AC; an adversarial re-read of adjacent code surfaces hidden scope) — `/spec` is the front line, `/qa` the safety net, so catching siblings here is strictly cheaper than at QA. Don't automate via grep — false-positive risk; this is a "look at adjacent code" planner prompt.
 
-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 (REQUIRED)
-
-**Every AC MUST have an explicit Verification Method.** 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]
-```
-
-#### Verification Method Decision Framework
-
-**REQUIRED:** Choose the most appropriate verification method for each AC:
-
-| AC Type | Verification Method | When to Use |
-|---------|---------------------|-------------|
-| Pure logic/calculation | **Unit Test** | Functions with clear input/output, no side effects |
-| API endpoint | **Integration Test** | HTTP handlers, database queries, external service calls |
-| User workflow | **Browser Test** | Multi-step UI interactions, form submissions |
-| Visual appearance | **Manual Test** | Styling, layout, animations (hard to automate) |
-| CLI command | **Integration Test** | Script execution, file operations, stdout verification |
-| Error handling | **Unit Test** + **Integration Test** | Both isolated behavior and realistic scenarios |
-| Performance | **Manual Test** + **Integration Test** | Timing thresholds, load testing |
-
-#### Verification Method Examples
-
-**Good (specific and testable):**
-```markdown
-**AC-1:** User can submit the registration form
-**Verification Method:** Browser Test
-**Test Scenario:**
-- Given: User on /register page
-- When: Fill form fields, click Submit
-- Then: Redirect to /dashboard, success toast appears
-```
-
-**Bad (vague, no clear verification):**
-```markdown
-**AC-1:** Registration should work properly
-**Verification Method:** ??? (cannot determine)
-```
-
-#### Flags for Missing Verification Methods
-
-If you cannot determine a verification method for an AC:
-
-1. **Flag the AC as unclear:**
-   ```markdown
-   **AC-3:** System handles errors gracefully
-   **Verification Method:** ⚠️ UNCLEAR - needs specific error scenarios
-   **Suggested Refinement:** List specific error types and expected responses
-   ```
-
-2. **Include in Open Questions:**
-   ```markdown
-   ## Open Questions
-
-   1. **AC-3 verification method unclear**
-      - Question: What specific error scenarios should be tested?
-      - Recommendation: Define 3-5 error types with expected behavior
-      - Impact: Without this, QA cannot objectively validate
-   ```
-
-**Why this matters:** AC without verification methods:
-- Cannot be objectively validated in `/qa`
-- Lead to subjective "does it work?" assessments
-- Cause rework when expectations don't match implementation
-
-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.
-
-### 2.5. Design Review (REQUIRED)
-
-**Purpose:** Make design decisions explicit before implementation starts. This forces evaluation of *how* to build, not just *what* to build — catching wrong-layer, over-engineered, or pattern-mismatched approaches before code is written.
-
-**Why this matters:** Repeated pattern across issues: implementation passes QA functionally but uses the wrong design — wrong layer, hacky shortcut, over-engineered approach. The fix cycle is expensive. Making design explicit here prevents it.
-
-**Complexity Scaling:**
-- **Simple issues** (`simple-fix`, `typo`, `docs-only` labels): Abbreviated — answer Q1 and Q3 only
-- **Standard issues**: Answer all 4 questions
-- **Complex issues** (`complex`, `refactor`, `breaking` labels): Answer all 4 questions with detailed rationale
-
-**Answer these questions:**
-
-1. **Where does this logic belong?** — Which module/layer owns this change? Name the specific directory, file, or abstraction layer. If it spans layers, explain why.
-
-2. **What's the simplest correct approach?** — Actively reject over-engineering. What's the minimum implementation that satisfies all AC? What alternatives did you consider and reject?
-
-3. **What existing pattern does this follow?** — Name the specific pattern in the codebase. Confirm it fits this use case. If no existing pattern fits, explain why a new approach is needed.
-
-4. **What would a senior reviewer challenge?** — Anticipate design pushback. What's the most likely "why didn't you just...?" or "this should be in X instead" feedback?
-
-**Example (standard issue):**
-
-```markdown
-## Design Review
-
-1. **Where does this logic belong?** Spec skill's SKILL.md prompt files — purely prompt engineering, not TypeScript. Same layer as Feature Quality Planning and AC Checklist sections.
-
-2. **What's the simplest correct approach?** Add markdown prompt text to SKILL.md. Reuse the existing complexity scaling pattern from Feature Quality Planning. No code, no new files, no abstractions.
-
-3. **What existing pattern does this follow?** Mirrors Feature Quality Planning exactly: required section, purpose statement, complexity scaling table, question format.
-
-4. **What would a senior reviewer challenge?** (1) "Why after Implementation Plan, not before?" — Design review needs the plan as input to evaluate. (2) "Won't this bloat output?" — Adds ~15 lines for standard, ~5 for simple-fix.
-```
-
-**Example (simple-fix issue, abbreviated):**
-
-```markdown
-## Design Review
-
-1. **Where does this logic belong?** `src/lib/utils.ts` — utility function, same layer as existing helpers.
-
-3. **What existing pattern does this follow?** Same pattern as `formatDuration()` in the same file — pure function, no side effects, single responsibility.
-```
+### Rule Touchpoints (Conditional)
 
-### 3. Feature Quality Planning (REQUIRED)
+**When to apply:** Any AC whose description matches the behavior-rule heuristic — i.e. >= 2 distinct keywords from `default | always | never | rule | behavior | skip` (case-insensitive), OR an explicit pattern like `always X unless Y` / `never X unless Y` / `default X when Y`.
 
-**Purpose:** Systematically consider professional implementation requirements beyond the minimum AC. This prevents gaps that slip through exec and QA because they were never planned.
+**Why:** Behavior-rule ACs are routinely implemented at multiple touchpoints — typically a skill prompt (LLM-interpreted) AND runtime TypeScript that duplicates the same rule. Without this check, edits land at one site and the other goes stale. Motivating miss: issue #533 (default /assess spec phase ON) where the runtime CLI's `BUG_LABELS`/`DOCS_LABELS` short-circuit survived the SKILL.md edit and was caught only by manual user follow-up. See [behavior-rule-detection.md](../_shared/references/behavior-rule-detection.md).
 
-**Why this matters:** Spec currently plans the "minimum to satisfy AC" rather than "complete professional implementation." Gaps found in manual review are omissions from incomplete planning, not failures.
-
-**Complexity Scaling:**
-- **Simple issues** (`simple-fix`, `typo`, `docs-only` labels): Use abbreviated checklist (Completeness + one relevant section)
-- **Standard issues**: Complete all applicable sections
-- **Complex issues** (`complex`, `refactor`, `breaking` labels): Complete all sections with detailed items
-
-```markdown
-## Feature Quality Planning
-
-### Completeness Check
-- [ ] All AC items have corresponding implementation steps
-- [ ] Integration points with existing features identified
-- [ ] No partial implementations or TODOs planned
-- [ ] State management considered (if applicable)
-- [ ] Data flow is complete end-to-end
-
-### Error Handling
-- [ ] Invalid input scenarios identified
-- [ ] API/external service failures handled
-- [ ] Edge cases documented (empty, null, max values)
-- [ ] Error messages are user-friendly
-- [ ] Graceful degradation planned
-
-### Code Quality
-- [ ] Types fully defined (no `any` planned)
-- [ ] Follows existing patterns in codebase
-- [ ] Error boundaries where needed
-- [ ] No magic strings/numbers
-- [ ] Consistent naming conventions
-
-### Test Coverage Plan
-- [ ] Unit tests for business logic
-- [ ] Integration tests for data flow
-- [ ] Edge case tests identified
-- [ ] Mocking strategy appropriate
-- [ ] Critical paths have test coverage
-
-### Best Practices
-- [ ] Logging for debugging/observability
-- [ ] Accessibility considerations (if UI)
-- [ ] Performance implications considered
-- [ ] Security reviewed (auth, validation, sanitization)
-- [ ] Documentation updated (if behavior changes)
-
-### Polish (UI features only)
-- [ ] Loading states planned
-- [ ] Error states have UI
-- [ ] Empty states handled
-- [ ] Responsive design considered
-- [ ] Keyboard navigation works
-
-### Derived ACs
-
-Based on quality planning, identify additional ACs needed:
-
-| Source | Derived AC | Priority |
-|--------|-----------|----------|
-| Error Handling | AC-N: Handle [specific error] with [specific response] | High/Medium/Low |
-| Test Coverage | AC-N+1: Add tests for [specific scenario] | High/Medium/Low |
-| Best Practices | AC-N+2: Add logging for [specific operation] | High/Medium/Low |
-
-**Note:** Derived ACs are numbered sequentially after original ACs and follow the same format.
-```
-
-**Section Applicability:**
-
-| Issue Type | Sections Required |
-|------------|-------------------|
-| Bug fix | Completeness, Error Handling, Test Coverage |
-| New feature | All sections |
-| Refactor | Completeness, Code Quality, Test Coverage |
-| UI change | All sections including Polish |
-| Backend/API | Completeness, Error Handling, Code Quality, Test Coverage, Best Practices |
-| CLI/Script | Completeness, Error Handling, Test Coverage, Best Practices |
-| Docs only | Completeness only |
-
-**Example (API endpoint feature):**
-
-```markdown
-## Feature Quality Planning
-
-### Completeness Check
-- [x] All AC items have corresponding implementation steps
-- [x] Integration points: Auth middleware, database queries, response serializer
-- [x] No partial implementations planned
-- [ ] State management: N/A (stateless API)
-- [x] Data flow: Request → Validate → Query → Transform → Response
-
-### Error Handling
-- [x] Invalid input: Return 400 with validation errors
-- [x] Auth failure: Return 401 with "Unauthorized" message
-- [x] Not found: Return 404 with resource ID
-- [x] Server error: Return 500, log full error, return generic message
-- [x] Rate limit: Return 429 with retry-after header
-
-### Code Quality
-- [x] Types: Define RequestDTO, ResponseDTO, ErrorResponse
-- [x] Patterns: Follow existing controller pattern in `src/api/`
-- [ ] Error boundaries: N/A (API, not UI)
-- [x] No magic strings: Use constants for error messages
-
-### Test Coverage Plan
-- [x] Unit: Validation logic, data transformation
-- [x] Integration: Full request/response cycle
-- [x] Edge cases: Empty results, max pagination, invalid IDs
-- [x] Mocking: Mock database, not HTTP layer
-
-### Best Practices
-- [x] Logging: Log request ID, duration, status code
-- [ ] Accessibility: N/A (API)
-- [x] Performance: Add database index for query field
-- [x] Security: Validate input, sanitize output, check auth
-
-### Derived ACs
-
-| Source | Derived AC | Priority |
-|--------|-----------|----------|
-| Error Handling | AC-6: Return 429 with retry-after header on rate limit | Medium |
-| Best Practices | AC-7: Log request ID and duration for observability | High |
-| Test Coverage | AC-8: Add integration test for auth failure path | High |
-```
-
-### 4. 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.5. Assess Comment Detection (AC-4, AC-5)
-
-**Before making your own phase recommendation**, check if `/assess` has already posted an analysis comment to this issue:
+**During context gathering**, run the detector on every AC. For each AC that triggers, list its touchpoints under a new `## Rule Touchpoints` section in the plan output.
 
 ```bash
-# Check for assess analysis comment on the issue (includes legacy /solve format for backward compat)
-assess_comment=$(gh issue view <issue-number> --json comments \
-  --jq '[.comments[].body | select(test("## Assess Analysis|## Solve Analysis|<!-- assess:phases=|<!-- solve:phases="))] | last // empty')
-```
-
-**If an assess analysis comment exists:**
-
-1. Parse the HTML comment markers to extract the recommended phases:
-   ```
-   <!-- assess:phases=exec,qa -->        → phases: ["exec", "qa"] (spec not included = skip spec)
-   <!-- assess:browser-test=false -->    → no browser testing needed
-   <!-- assess:quality-loop=true -->     → enable quality loop
-   ```
-
-2. **Use the assess recommendation as your starting point** for the phase recommendation in step 5.
-
-3. **You may override the assess recommendation**, but you MUST document why:
-   ```markdown
-   ## Recommended Workflow
-
-   **Phases:** spec → exec → test → qa
-   **Quality Loop:** enabled
-   **Reasoning:** Assess recommended `exec → qa`, but codebase analysis reveals UI components
-   are affected (found `.tsx` files in change scope), so browser testing is needed.
-   Overriding assess recommendation with explanation.
-   ```
-
-4. If the assess comment recommends phases that don't include `spec` (e.g., `phases=exec,qa`), acknowledge this in your output but proceed with spec since `/spec` was explicitly invoked.
-
-**If no assess 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
-**Reasoning:** [Brief explanation of why these phases were chosen]
-```
-
-**Phase Selection Logic:**
-- **UI/Frontend changes** → Add `test` phase (browser testing)
-- **`no-browser-test` label** → Skip `test` phase (explicit opt-out, overrides UI labels)
-- **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`
-- **New features with testable ACs** → Add `testgen` phase after spec
-- **Refactors needing regression tests** → Add `testgen` phase
-
-#### 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
-
-#### Testgen Phase Auto-Detection
-
-**When to recommend `testgen` phase:**
-
-| Condition | Recommend testgen? | Reasoning |
-|-----------|-------------------|-----------|
-| ACs have "Unit Test" verification method | ✅ Yes | Tests should be stubbed before implementation |
-| ACs have "Integration Test" verification method | ✅ Yes | Complex integration tests benefit from early structure |
-| Issue is a new feature (not bug fix) with >2 AC items | ✅ Yes | Features need test coverage |
-| Issue has `enhancement` or `feature` label | ✅ Yes | New functionality needs tests |
-| Project has test framework (Jest, Vitest, etc.) | ✅ Yes | Infrastructure exists to run tests |
-| Issue is a simple bug fix (`bug` label only) | ❌ No | Bug fixes typically have targeted tests |
-| Issue is docs-only (`docs` label) | ❌ No | Documentation doesn't need unit tests |
-| All ACs have "Manual Test" or "Browser Test" verification | ❌ No | These don't generate code stubs |
-
-**Detection Logic:**
-
-1. **Check verification methods in AC items:**
-   - Count ACs with "Unit Test" → If >0, recommend testgen
-   - Count ACs with "Integration Test" → If >0, recommend testgen
-
-2. **Check issue labels:**
-   ```bash
-   gh issue view <issue> --json labels --jq '.labels[].name'
-   ```
-   - If `bug` or `fix` is the ONLY label → Skip testgen
-   - If `docs` is present → Skip testgen
-   - If `enhancement`, `feature`, `refactor` → Consider testgen
-
-3. **Check project test infrastructure:**
-   ```bash
-   # Check for test framework in package.json
-   grep -E "jest|vitest|mocha" package.json || true
-   ```
-   - If no test framework detected → Skip testgen (no infrastructure)
-
-**Example output when testgen is recommended:**
-
-```markdown
-## Recommended Workflow
-
-**Phases:** spec → testgen → exec → qa
-**Quality Loop:** disabled
-**Reasoning:** ACs include Unit Test verification methods; testgen will create stubs before implementation
-```
-
-**Example output when testgen is NOT recommended:**
-
-```markdown
-## Recommended Workflow
-
-**Phases:** spec → exec → qa
-**Quality Loop:** disabled
-**Reasoning:** Bug fix with targeted scope; existing tests sufficient
+# Per-AC touchpoint enumeration. Run once per AC in the issue body.
+# Skip entirely when no AC triggers (cheap short-circuit).
+SPEC_AC_ID="AC-1" \
+SPEC_AC_TEXT="<verbatim AC description from the issue body>" \
+npx tsx -e '
+(async () => {
+  const m = await import("./src/lib/heuristics/behavior-rule-detector.ts");
+  const ac = {
+    id: process.env.SPEC_AC_ID,
+    description: process.env.SPEC_AC_TEXT,
+    verificationMethod: "manual",
+    status: "pending",
+  };
+  const detection = m.detectBehaviorRule(ac);
+  if (!detection.triggered) { console.log(JSON.stringify({ triggered: false })); return; }
+  const touchpoints = m.findTouchpoints(ac, process.cwd());
+  console.log(JSON.stringify({ triggered: true, keywords: detection.keywords, touchpoints }));
+})();
+'
 ```
 
-### 6. Label Review
-
-Analyze current labels vs implementation plan and suggest updates:
+**If any AC triggers and `touchpoints` is non-empty**, add this section to the plan output (between **Implementation Plan** and **Design Review**):
 
 ```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).
+## Rule Touchpoints
 
-### 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
+| AC | Touchpoint | Snippet |
+|----|------------|---------|
+| AC-N | path/to/file.ts:LINE | `<one-line snippet>` |
 ```
 
-### State Updates (Standalone Only)
+**If every AC short-circuits** (`triggered: false`) **or `touchpoints` is empty**, omit the section entirely — keeps cost cheap per the Performance budget in the reference doc.
 
-When NOT orchestrated (`SEQUANT_ORCHESTRATOR` is not set):
 
-**At skill start:**
-```bash
-npx tsx scripts/state/update.ts start <issue-number> spec
-```
+## Verification Method Decision Framework
 
-**On successful completion:**
-```bash
-npx tsx scripts/state/update.ts complete <issue-number> spec
-```
+Use this table when assigning verification methods to each AC:
 
-**On failure:**
-```bash
-npx tsx scripts/state/update.ts fail <issue-number> spec "Error description"
-```
+| AC Type | Method | When to Use |
+|---------|--------|-------------|
+| Pure logic/calculation | Unit Test | Clear input/output, no side effects |
+| API endpoint | Integration Test | HTTP handlers, DB queries, external calls |
+| User workflow | Browser Test | Multi-step UI interactions, forms |
+| Visual appearance | Manual Test | Styling, layout, animations |
+| CLI command | Integration Test | Script execution, stdout verification |
+| Error handling | Unit + Integration | Both isolated and realistic scenarios |
 
-**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)
-- [ ] **Scope Assessment** - Verdict and metrics (or "Skipped" if --skip-scope-check)
-- [ ] **Non-Goals Section** - Listed or warning if missing
-- [ ] **AC Checklist** - Numbered AC items (AC-1, AC-2, etc.) with descriptions
-- [ ] **Verification Criteria (REQUIRED)** - Each AC MUST have:
-  - Explicit Verification Method (Unit Test, Integration Test, Browser Test, or Manual Test)
-  - Test Scenario with Given/When/Then format
-  - If unclear, flag as "⚠️ UNCLEAR" and add to Open Questions
-- [ ] **Conflict Risk Analysis** - Check for in-flight work, include if conflicts found
-- [ ] **Implementation Plan** - 3-7 concrete steps with codebase references
-- [ ] **Design Review** - All 4 questions answered (abbreviated to Q1+Q3 for simple-fix/typo/docs-only labels)
-- [ ] **Feature Quality Planning** - Quality dimensions checklist completed (abbreviated for simple-fix/typo/docs-only labels)
-- [ ] **Recommended Workflow** - Phases, Quality Loop setting, and Reasoning (auto-enable quality loop if scope is yellow/red)
-- [ ] **Label Review** - Current vs recommended labels based on plan analysis
-- [ ] **Open Questions** - Any ambiguities with recommended defaults (including unclear verification methods)
-- [ ] **Issue Comment Draft** - Formatted for GitHub posting
-
-**CRITICAL:** Do NOT output AC items without verification methods. Either:
-1. Assign a verification method from the decision framework, or
-2. Flag as "⚠️ UNCLEAR" and include in Open Questions
-
-**DO NOT respond until all items are verified.**
+See [verification-criteria.md](references/verification-criteria.md) for detailed examples.
 
 ## Output Template
 
-You MUST include these sections in order:
+**Single authoritative template.** Include ALL sections in this order. Scale detail by complexity tier.
 
 ```markdown
+**Complexity: [Simple|Standard|Complex]** ([N] ACs, [N] directories)
+
 ## AC Quality Check
 
-[Output from AC linter, or "Skipped (--skip-ac-lint flag set)"]
+[Inline analysis results, or "Skipped (--skip-ac-lint)"]
 
 ---
 
 ## Scope Assessment
 
-### Non-Goals (Required)
-
-[List non-goals from issue, or warning if missing]
-
-### Scope Metrics
+**Non-Goals:** [From issue body. If missing: "⚠️ Non-Goals section not found. Consider adding scope boundaries."]
 
 | Metric | Value | Status |
 |--------|-------|--------|
@@ -1007,9 +232,9 @@ You MUST include these sections in order:
 | AC items | [N] | [✅/⚠️/❌] |
 | Directory spread | [N] | [✅/⚠️/❌] |
 
-### Scope Verdict
+**Verdict:** [✅ SCOPE_OK | ⚠️ SCOPE_WARNING | ❌ SCOPE_SPLIT_RECOMMENDED]
 
-[✅/⚠️/❌] **[SCOPE_OK/SCOPE_WARNING/SCOPE_SPLIT_RECOMMENDED]** - [Recommendation]
+[Or "Skipped (--skip-scope-check)"]
 
 ---
 
@@ -1017,116 +242,93 @@ You MUST include these sections in order:
 
 ### 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]
-
-**Verification Method:** [Choose from decision framework]
+**Verification:** [Unit Test | Integration Test | Browser Test | Manual Test]
+**Scenario:** Given [state] → When [action] → Then [outcome]
+**Assumptions:** [List any that need pre-coding validation]
 
-**Test Scenario:**
-- Given: [Initial state]
-- When: [Action]
-- Then: [Expected outcome]
+<!-- Repeat for all ACs. EVERY AC must have a Verification Method from the decision framework.
+     If unclear, flag as "⚠️ UNCLEAR" with suggested refinement. -->
 
-### AC-N: [Unclear AC example]
+<!-- Example of a completed AC entry:
 
-**Verification Method:** ⚠️ UNCLEAR - [reason why verification is unclear]
+### AC-3: User can submit the registration form
 
-**Suggested Refinement:** [How to make this AC testable]
-
-<!-- Continue for all AC items -->
+**Verification:** Browser Test
+**Scenario:** Given user on /register → When fill fields and click Submit → Then redirect to /dashboard with success toast
+**Assumptions:** Auth API returns 201 on valid input; email uniqueness enforced by DB constraint
+-->
 
 ---
 
 ## Implementation Plan
 
-### Phase 1: [Phase Name]
-1. [Step with specific file/component references]
+### Phase 1: [Name]
+1. [Step referencing specific files/components from context gathering]
 2. [Step]
 
-### Phase 2: [Phase Name]
-<!-- Continue for all phases -->
+### Phase 2: [Name]
+<!-- 3-7 total steps. Group into phases. Note dependencies between steps.
+     For major decisions: present 2-3 options, recommend default with rationale.
+     See references/parallel-groups.md for parallel execution format (3+ independent tasks). -->
 
 ---
 
 ## Design Review
 
 1. **Where does this logic belong?** [Module/layer that owns this change]
-
 2. **What's the simplest correct approach?** [Minimum implementation, rejected alternatives]
+3. **What existing pattern does this follow?** [Named pattern, confirm it fits]
+4. **What would a senior reviewer challenge?** [Anticipated "why didn't you just...?" pushback]
 
-3. **What existing pattern does this follow?** [Named pattern, confirmation it fits]
-
-4. **What would a senior reviewer challenge?** [Anticipated pushback]
-
-<!-- For simple-fix/typo/docs-only: only Q1 and Q3 required -->
+<!-- Simple tier: Q1 and Q3 only. Standard/Complex: all four. -->
 
 ---
 
 ## Feature Quality Planning
 
-### Completeness Check
-- [ ] All AC items have corresponding implementation steps
-- [ ] Integration points identified
-- [ ] No partial implementations planned
-
-### Error Handling
-- [ ] Invalid input scenarios identified
-- [ ] External service failures handled
-- [ ] Edge cases documented
+<!-- Exception-based: report only gaps and concerns. Full checklist in references/quality-checklist.md -->
 
-### Code Quality
-- [ ] Types fully defined (no `any`)
-- [ ] Follows existing patterns
-- [ ] No magic strings/numbers
+**All standard checks pass.** Notable items:
+- [Gap or concern requiring attention]
+- [Another gap if applicable]
 
-### Test Coverage Plan
-- [ ] Unit tests for business logic
-- [ ] Edge case tests identified
-- [ ] Critical paths covered
+### Derived ACs (if any)
 
-### Best Practices
-- [ ] Logging for observability
-- [ ] Security reviewed
-- [ ] Documentation updated
-
-### Polish (UI only)
-- [ ] Loading/error/empty states
-- [ ] Responsive design
-
-### Derived ACs
 | Source | Derived AC | Priority |
 |--------|-----------|----------|
-| [Section] | AC-N: [Description] | High/Medium/Low |
+| [Quality dimension] | AC-N: [Description] | High/Medium/Low |
+
+<!-- Complex tier: walk through full checklist from references/quality-checklist.md -->
 
 ---
 
 ## Open Questions
 
-1. **[Question]**
-   - Recommendation: [Default choice]
-   - Impact: [What happens if wrong]
+1. **[Question]** — Recommendation: [default]. Impact: [if wrong].
 
 ---
 
 ## Recommended Workflow
 
-**Phases:** exec → qa
-**Quality Loop:** disabled
-**Reasoning:** [Why these phases based on issue analysis]
+**Phases:** [spec →] exec → qa
+**Quality Loop:** [enabled/disabled]
+**Reasoning:** [Brief explanation]
+
+<!-- Decision logic:
+     - UI/frontend → add `test` phase
+     - `no-browser-test` label → skip `test` (overrides UI labels)
+     - Complex refactor → enable quality loop
+     - Security-sensitive → add `security-review` phase
+     - New features with Unit/Integration Test verification ACs → add `testgen` phase
+     - Docs-only → skip spec, just exec → qa -->
 
 ---
 
 ## Label Review
 
-**Current:** [current labels]
-**Recommended:** [recommended labels]
-**Reason:** [Why these labels based on plan analysis]
+**Current:** [labels]
+**Recommended:** [labels]
+**Reason:** [Why, based on plan analysis]
 **Quality Loop:** [Will/Won't auto-enable and why]
 
 → `gh issue edit <N> --add-label [label]`
@@ -1135,5 +337,56 @@ You MUST include these sections in order:
 
 --- DRAFT GITHUB ISSUE COMMENT (PLAN) ---
 
-[Complete formatted comment for GitHub]
+[AC checklist with verification + implementation plan + key decisions + open questions]
+```
+
+### Testgen Phase Auto-Detection
+
+#### When to recommend `testgen` phase:
+
+| Condition | Recommend testgen? | Reasoning |
+|-----------|-------------------|-----------|
+| ACs have "Unit Test" verification method | Yes | Tests should be stubbed before implementation |
+| ACs have "Integration Test" verification method | Yes | Complex integration tests benefit from early structure |
+| New feature (`enhancement`/`feature` label) with >2 ACs | Yes | Features need test coverage |
+| Simple bug fix (`bug` label only) | No | Skip testgen — targeted tests sufficient |
+| Docs-only (`docs` label) | No | Skip testgen — no unit tests needed |
+| All ACs have "Manual Test" or "Browser Test" | No | Skip testgen — no code stubs to generate |
+
+**Detection logic:**
+1. Count ACs with "Unit Test" → If >0, recommend testgen
+2. Count ACs with "Integration Test" → If >0, recommend testgen
+3. Check labels: `bug`/`fix` only → Skip testgen. `docs` → Skip testgen.
+
+**Example when testgen recommended:**
+```markdown
+**Phases:** spec → testgen → exec → qa
+**Reasoning:** ACs include Unit Test verification methods; testgen will create stubs before implementation
+```
+
+### Browser Testing Label Suggestion
+
+When `.tsx`/`.jsx` references detected in issue body AND no `ui`/`frontend`/`admin` label present:
+> **Component files detected** — add `ui` label for browser testing, or `no-browser-test` to explicitly skip.
+
+### Assess Comment Integration
+
+Before making phase recommendations, check for prior `/assess` analysis:
+
+```bash
+assess_comment=$(gh issue view <N> --json comments \
+  --jq '[.comments[].body | select(test("## Assess Analysis|<!-- assess:phases="))] | last // empty')
 ```
+
+If found, use assess recommendation as starting point. You may override, but MUST document why.
+
+## Update GitHub Issue
+
+Post the draft comment and add label:
+
+```bash
+gh issue comment <issue-number> --body "..."
+gh issue edit <issue-number> --add-label "planned"
+```
+
+**Do NOT start implementation** — this is planning-only.