sequant 1.20.3 → 2.0.0

package/templates/skills/spec/SKILL.md

@@ -391,6 +391,51 @@ For each major decision:
 
 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.
+```
+
 ### 3. Plan Review
 
 Ask the user to confirm or adjust:
@@ -404,24 +449,24 @@ Ask the user to confirm or adjust:
 
 **Before** determining the recommended workflow, analyze the issue content for phase-relevant signals:
 
-#### Step 1: Check for Solve Comment (AC-4)
+#### Step 1: Check for Assess Comment (AC-4)
 
-First, check if a `/solve` comment already exists for this issue:
+First, check if an `/assess` 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
+# Check issue comments for assess workflow (includes legacy /solve format for backward compat)
+gh issue view <issue-number> --json comments --jq '.comments[].body' | grep -l "## Assess Analysis\|## 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"`
+**If assess comment found:**
+- Extract phases from the assess workflow (e.g., `spec → exec → test → qa`)
+- Use assess recommendations as the primary source (after labels)
+- Skip content analysis for phases (assess already analyzed)
+- Include in output: `"Assess comment found - using /assess workflow recommendations"`
 
 #### Step 2: Analyze Title for Keywords (AC-1)
 
-If no solve comment, analyze the issue title for phase-relevant keywords:
+If no assess comment, analyze the issue title for phase-relevant keywords:
 
 | Pattern | Detection | Suggested Phase |
 |---------|-----------|-----------------|
@@ -468,7 +513,7 @@ Content analysis **supplements** label detection - it can only ADD phases, never
 
 **Priority order (highest first):**
 1. **Labels** (explicit, highest priority)
-2. **Solve comment** (if exists)
+2. **Assess comment** (if exists)
 3. **Title keywords**
 4. **Body patterns** (lowest priority)
 
@@ -491,42 +536,41 @@ Content analysis **supplements** label detection - it can only ADD phases, never
 **Final phases:** spec → exec → test → security-review → qa
 ```
 
-### 4.5. Solve Comment Detection (AC-4, AC-5)
+### 4.5. Assess Comment Detection (AC-4, AC-5)
 
-**Before making your own phase recommendation**, check if `/solve` has already posted an analysis comment to this issue:
+**Before making your own phase recommendation**, check if `/assess` 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')
+# 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 a solve analysis comment exists:**
+**If an assess 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
+   <!-- 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 solve recommendation as your starting point** for the phase recommendation in step 5.
+2. **Use the assess recommendation as your starting point** for the phase recommendation in step 5.
 
-3. **You may override the solve recommendation**, but you MUST document why:
+3. **You may override the assess 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
+   **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 solve recommendation with explanation.
+   Overriding assess 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.
+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 solve analysis comment exists:** Proceed with your own analysis as normal (step 5).
+**If no assess analysis comment exists:** Proceed with your own analysis as normal (step 5).
 
 ### 5. Recommended Workflow
 
@@ -654,7 +698,8 @@ npx tsx scripts/state/update.ts fail <issue-number> spec "Error description"
 - [ ] **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)
+- [ ] **Design Review** - All 4 questions answered (abbreviated to Q1+Q3 for simple-fix/typo/docs-only labels)
+- [ ] **Content Analysis** - Title/body analysis results (or "Assess comment found" if using /assess)
 - [ ] **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
@@ -700,6 +745,20 @@ You MUST include these sections in order:
 
 ---
 
+## 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, confirmation it fits]
+
+4. **What would a senior reviewer challenge?** [Anticipated pushback]
+
+<!-- For simple-fix/typo/docs-only: only Q1 and Q3 required -->
+
+---
+
 ## Open Questions
 
 1. **[Question]**
@@ -710,10 +769,10 @@ You MUST include these sections in order:
 
 ## Content Analysis
 
-<!-- If solve comment found: -->
-**Source:** Solve comment found - using /solve workflow recommendations
+<!-- If assess comment found: -->
+**Source:** Assess comment found - using /assess workflow recommendations
 
-<!-- If no solve comment, show analysis: -->
+<!-- If no assess comment, show analysis: -->
 ### Signal Sources
 
 | Phase | Source | Confidence | Reason |