@simplysm/sd-claude 13.0.76 → 13.0.78

package/claude/skills/sd-explore/SKILL.md

@@ -1,76 +1,118 @@
 ---
 name: sd-explore
-description: "Use when the user asks to explore, analyze, trace, or understand code structure, architecture, or implementation flow. Triggers: 'explore this', 'how does this work', 'analyze this code', 'trace the flow', 'what does this package do', codebase understanding requests."
-model: sonnet
+description: "Use when analyzing a large codebase (30+ files) that must be read comprehensively. Splits files into groups and dispatches parallel sub-agents to avoid context compaction and information loss."
 ---
 
 # sd-explore
 
-You are an expert code analyst. Trace implementations across codebases and save structured analysis to file.
+## Overview
 
-## Target Selection
+Split a large codebase into manageable groups and dispatch parallel sub-agents, each reading its assigned files and writing results to disk. The calling skill then reads result files instead of raw source — no context compaction, no information loss.
 
-**When invoked with `$ARGUMENTS`:**
+**Core principle:** Never read 30+ files in a single agent context. Split, parallelize, write to files.
 
-- If path is provided → **Immediately start analysis** (don't ask clarifying questions)
-- If path is a package directory → Trace all major features, architecture, and patterns
-- If path is a single file → Trace its role, dependencies, and usage
-- If no arguments provided → Ask the user what to explore
+**Important:** This is a workflow the **orchestrator (main agent)** follows directly. Do NOT delegate the entire sd-explore workflow to a sub-agent — only the orchestrator has `Agent` tool access to dispatch parallel sub-agents. The orchestrator globs files, splits groups, and dispatches `Agent(Explore)` calls itself.
 
-**Analysis only — no code modifications.**
+## When to Use
 
-## Output — Save to File
+- Codebase analysis covering 30+ source files
+- Called by other skills (sd-review, sd-brainstorm, sd-debug, sd-plan) that need comprehensive file reading
+- Any task where reading all files sequentially would risk context compaction
 
-**All analysis results MUST be saved to `.tmp/explore/`.** Do NOT dump the full analysis into the conversation.
+**When NOT to use:**
+- < 30 files — a single agent can handle it directly
+- Targeted search for a specific function/class — use Grep/Glob instead
 
-This prevents context loss from compaction and makes results available to subsequent skills/agents.
+## Input
 
-### File Naming
+The calling skill provides:
 
-- **Directory/package analysis:** `.tmp/explore/{package-name}.md` (e.g., `.tmp/explore/solid.md`)
-- **Single file analysis:** `.tmp/explore/{filename}.md` (e.g., `.tmp/explore/Dialog.md`)
-- **Sub-topic deep dive:** `.tmp/explore/{package-name}--{topic}.md` (e.g., `.tmp/explore/solid--form-controls.md`)
+1. **Target path** — directory to explore (e.g., `packages/solid/src`)
+2. **Name** — caller identifier for output filenames (e.g., `review`, `debug`, `brainstorm`)
+3. **File patterns** — glob patterns to match (default: `**/*.ts`, `**/*.tsx`; exclude `node_modules`, `dist`)
+4. **Analysis instructions** — free-form text describing what each sub-agent should do
 
-### File Structure
+The analysis instructions are passed verbatim to each sub-agent. They can request anything: tags, summaries, pattern searches, specific questions, etc.
 
-```markdown
-# {Target Name} — Explore
+## Workflow
+
+### Step 1: Discover Files
+
+Glob all matching files under the target path.
+
+- **< 30 files**: Run a single `Agent(subagent_type=Explore)` with the analysis instructions. No splitting needed. Write result to `.tmp/explore/{dt}_{name}.md` (where `{dt}` is current datetime as `yyyyMMddHHmmss`).
+- **>= 30 files**: Proceed to Step 2.
+
+### Step 2: Split Into Groups
 
-> Analyzed: {target path}
+Split files into groups of **~30 files each**.
 
-## Summary
-{1-3 sentence overview}
+**Splitting strategy:**
 
-## Architecture
-{Design patterns, layers, key abstractions}
+1. List all subdirectories under target
+2. Group files by subdirectory, keeping each group around 30 files
+3. If the target is mostly flat (few subdirectories), group by file proximity (alphabetical chunks)
+4. Adjacent small directories can be merged into one group
+5. A single large directory (40+ files) should be split into multiple groups
 
-## Entry Points
-{APIs, components, commands — with file:line references}
+**Goal:** Balanced groups where related files stay together.
 
-## Code Flow
-{Step-by-step execution traces}
+### Step 3: Dispatch Parallel Agents
 
-## Key Files
-{Essential files for understanding the target — with file:line references}
+Launch one `Agent(subagent_type=Explore)` per group, **all in a single message** for true parallelism.
 
-## Dependencies
-{Internal and external dependencies}
+Each agent receives:
 
-## Observations
-{Strengths, issues, opportunities}
 ```
+You are exploring a section of a codebase. Read ALL assigned files and write your analysis to the output file.
 
-### Workflow
+**Assigned files:**
+[list of file paths for this group]
 
-1. Perform the analysis (read files, trace code, map architecture)
-2. Write the full result to `.tmp/explore/{name}.md`
-3. Output a **brief summary** to the conversation (3-5 lines max) with the file path
+**Analysis instructions:**
+[caller's free-form instructions, passed verbatim]
 
-**Example conversation output:**
+**Output file:** .tmp/explore/{dt}_{name}-{group_index}.md
+
+Read every assigned file. Write your complete analysis to the output file. Do NOT skip files.
 ```
-Analyzed `packages/solid/src/components/disclosure/` → saved to `.tmp/explore/solid--disclosure.md`
 
-- 4 components: Dialog, Dropdown, Collapse, Tabs
-- Shared pattern: portal + backdrop + animation via CSS transitions
-- Key file: Dialog.tsx:45 — base implementation others extend
+### Step 4: Return Result Paths
+
+After all agents complete, return the list of output file paths to the calling skill.
+
+The calling skill reads these files to get the analysis results — the main context stays clean.
+
+## Output Format
+
+Each sub-agent writes to its assigned output file. The format is determined by the caller's analysis instructions. If no specific format is requested, use:
+
+```markdown
+# Explore: [directory names]
+
+## File Summaries
+- `path/to/file.ts` — Brief description
+
+## Analysis
+[Results per the caller's instructions]
 ```
+
+## Why Sub-Agents Matter
+
+The value is **context isolation**, not just speed:
+
+- **Without sub-agents**: Reading 100+ files in the main context causes compaction. Earlier file analyses get dropped, degrading quality of later analysis steps (review, planning, etc.)
+- **With sub-agents**: Each sub-agent reads ~30 files in its own context, writes results to disk, and exits. The main context only reads the summary files — staying clean for subsequent work.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Delegating the entire workflow to a sub-agent | The orchestrator follows sd-explore directly — only it can dispatch parallel `Agent` calls |
+| Reading all files in one agent | Split into groups of ~30, dispatch parallel agents |
+| Not writing results to files | Each agent MUST write to its output file — this is what prevents context bloat |
+| Groups too large (50+) | Keep groups around 30 files for reliable coverage |
+| Groups too small (5-10) | Wastes agent overhead — merge small directories |
+| Not passing analysis instructions verbatim | The caller's instructions go to each agent as-is |
+| Running agents sequentially | Launch all agents in a single message for parallelism |
+| Skipping Step 1 threshold check | < 30 files don't need splitting — avoid unnecessary overhead |

package/claude/skills/sd-plan/SKILL.md

@@ -138,7 +138,6 @@ git commit -m "feat: add specific feature"
 ## Related Skills
 
 - **sd-brainstorm** — prerequisite: creates the design this skill plans from
-- **sd-explore** — for deeper codebase exploration when gathering context
 - **sd-plan-dev** — executes the plan this skill creates
 
 ## Execution Handoff

package/claude/skills/sd-plan-dev/SKILL.md

@@ -11,15 +11,11 @@ Execute plan tasks via parallel implementers with dependency-aware scheduling.
 
 ## When to Use
 
-```dot
-digraph when_to_use {
-    "Have implementation plan?" [shape=diamond];
-    "sd-plan-dev" [shape=box];
-    "Manual execution or brainstorm first" [shape=box];
-
-    "Have implementation plan?" -> "sd-plan-dev" [label="yes"];
-    "Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"];
-}
+```mermaid
+flowchart TD
+    A{Have implementation plan?}
+    A -->|yes| B[sd-plan-dev]
+    A -->|no| C[Manual execution or brainstorm first]
 ```
 
 ## Execution Method
@@ -41,78 +37,49 @@ Independent tasks run as **parallel Task calls in a single message**. After impl
 
 ## The Process
 
-```dot
-digraph process {
-    rankdir=TB;
-
-    "Read plan, extract tasks, create TaskCreate" [shape=box];
-    "Dependency analysis: identify files per task, build graph, group into batches" [shape=box];
-
-    subgraph cluster_batch {
-        label="Per Batch (independent tasks)";
-
-        subgraph cluster_parallel_implementers {
-            label="Parallel implementer Task calls (single message)";
-            style=dashed;
-
-            subgraph cluster_implementer {
-                label="Each Implementer";
-                "Implement the task" [shape=box];
-                "Questions?" [shape=diamond];
-                "Return questions to orchestrator" [shape=box];
-                "Re-launch with answers" [shape=box];
-                "Commit and report" [shape=box];
-            }
-        }
-
-        subgraph cluster_review {
-            label="Orchestrator review loop (per implementer)";
-
-            subgraph cluster_parallel_reviewers {
-                label="Parallel reviewer Task calls (single message)";
-                style=dashed;
-                "Task: spec reviewer" [shape=box];
-                "Task: quality reviewer" [shape=box];
-            }
-
-            "Any issues?" [shape=diamond];
-            "Task: implementer fix" [shape=box];
-            "Re-review (parallel Task calls)" [shape=box];
-        }
-    }
-
-    "More batches?" [shape=diamond];
-    "Batch integration check (typecheck + lint)" [shape=box];
-    "Task: final review for entire implementation" [shape=box];
-    "Done" [shape=ellipse];
-
-    "Read plan, extract tasks, create TaskCreate" -> "Dependency analysis: identify files per task, build graph, group into batches";
-    "Dependency analysis: identify files per task, build graph, group into batches" -> "Implement the task";
-    "Implement the task" -> "Questions?";
-    "Questions?" -> "Return questions to orchestrator" [label="yes"];
-    "Return questions to orchestrator" -> "Re-launch with answers";
-    "Re-launch with answers" -> "Implement the task";
-    "Questions?" -> "Commit and report" [label="no"];
-    "Commit and report" -> "Task: spec reviewer";
-    "Commit and report" -> "Task: quality reviewer";
-    "Task: spec reviewer" -> "Any issues?";
-    "Task: quality reviewer" -> "Any issues?";
-    "Any issues?" -> "Task: implementer fix" [label="yes"];
-    "Task: implementer fix" -> "Re-review (parallel Task calls)";
-    "Re-review (parallel Task calls)" -> "Any issues?";
-    "Any issues?" -> "Batch integration check (typecheck + lint)" [label="no"];
-    "Batch integration check (typecheck + lint)" -> "More batches?";
-    "More batches?" -> "Implement the task" [label="yes, next batch"];
-    "More batches?" -> "Task: final review for entire implementation" [label="no"];
-    "Run /simplify on all changed code" [shape=box];
-    "Changes made?" [shape=diamond];
-
-    "Task: final review for entire implementation" -> "Run /simplify on all changed code";
-    "Run /simplify on all changed code" -> "Changes made?";
-    "Changes made?" -> "Typecheck + lint affected packages" [label="yes"];
-    "Typecheck + lint affected packages" -> "Done";
-    "Changes made?" -> "Done" [label="no"];
-}
+```mermaid
+flowchart TD
+    A["Read plan, extract tasks, create TaskCreate"] --> B["Dependency analysis: identify files per task, build graph, group into batches"]
+
+    subgraph BATCH["Per Batch (independent tasks)"]
+        subgraph PAR_IMPL["Parallel implementer Task calls (single message)"]
+            subgraph IMPL["Each Implementer"]
+                C["Implement the task"] --> D{"Questions?"}
+                D -->|yes| E["Return questions to orchestrator"]
+                E --> F["Re-launch with answers"]
+                F --> C
+                D -->|no| G["Commit and report"]
+            end
+        end
+
+        subgraph REVIEW["Orchestrator review loop (per implementer)"]
+            subgraph PAR_REV["Parallel reviewer Task calls (single message)"]
+                H["Task: spec reviewer"]
+                I["Task: quality reviewer"]
+            end
+            J{"Any issues?"}
+            K["Task: implementer fix"]
+            L["Re-review (parallel Task calls)"]
+        end
+    end
+
+    B --> C
+    G --> H
+    G --> I
+    H --> J
+    I --> J
+    J -->|yes| K
+    K --> L
+    L --> J
+    J -->|no| M["Batch integration check (typecheck + lint)"]
+    M --> N{"More batches?"}
+    N -->|"yes, next batch"| C
+    N -->|no| O["Task: final review for entire implementation"]
+    O --> P["Run /simplify on all changed code"]
+    P --> Q{"Changes made?"}
+    Q -->|yes| R["Typecheck + lint affected packages"]
+    R --> S(["Done"])
+    Q -->|no| S
 ```
 
 ## Dependency Analysis
@@ -323,6 +290,5 @@ After simplify completes (or is skipped), report to the user: number of tasks co
 **Related skills:**
 
 - **sd-plan** — creates the plan this skill executes
-- **sd-explore** — for codebase exploration when implementers need deeper context
 - **sd-tdd** — implementers follow TDD
 - **sd-worktree** — branch isolation for worktree-based workflows

package/claude/skills/sd-review/SKILL.md

@@ -7,18 +7,18 @@ description: "Use when the user explicitly requests code review, refactoring ana
 
 ## Overview
 
-Comprehensive code analysis combining **defect review** (correctness, safety, API, conventions) and **refactoring analysis** (structure, simplification). Dispatches up to 5 reviewer agents in parallel, verifies findings against actual code, and compiles a unified report.
+Comprehensive code analysis combining **defect review** (correctness, safety, API, conventions) and **refactoring analysis** (structure, simplification). Uses **sd-explore** to minimize redundant file reads, then dispatches reviewers with pre-filtered context.
 
 **Analysis only — no code modifications.**
 
 ## Principles
 
-- **Breaking changes are irrelevant**: Reviewers must NOT dismiss, soften, or deprioritize findings because the suggested fix would cause a breaking change. Correctness, safety, usability, architecture, and maintainability always take priority over API stability. If something is wrong, report it — regardless of breaking change impact.
+- **Breaking changes are irrelevant**: Reviewers must NOT dismiss findings because the fix would cause a breaking change.
 
 ## Usage
 
 - `/sd-review packages/solid` — full review (all perspectives)
-- `/sd-review packages/solid focus on bugs` — selective review based on request
+- `/sd-review packages/solid focus on bugs` — selective review
 - `/sd-review packages/solid focus on refactoring` — structural analysis only
 - `/sd-review` — if no argument, ask the user for the target path
 
@@ -31,125 +31,152 @@ Comprehensive code analysis combining **defect review** (correctness, safety, AP
 
 ## Reviewer Perspectives
 
-| Reviewer | Prompt Template | Perspective |
-|----------|----------------|-------------|
-| **Code Reviewer** | `code-reviewer-prompt.md` | Correctness & Safety — bugs, security, logic errors, architectural defects (circular deps, boundary violations) |
-| **API Reviewer** | `api-reviewer-prompt.md` | Usability & DX — naming, types, consistency |
-| **Convention Checker** | `convention-checker-prompt.md` | Project rules — Grep-based systematic check against convention files (prohibited patterns, naming rules, export rules) |
-| **Code Simplifier** | `code-simplifier-prompt.md` | Simplification — complexity, duplication, readability |
-| **Structure Analyzer** | `structure-analyzer-prompt.md` | Organization — responsibility separation, abstraction levels, module structure |
+| Reviewer | Prompt Template | Tag | Perspective |
+|----------|----------------|-----|-------------|
+| **Code Reviewer** | `code-reviewer-prompt.md` | `[CORRECTNESS]` | Correctness & Safety |
+| **API Reviewer** | `api-reviewer-prompt.md` | `[API]` | Usability & DX |
+| **Convention Checker** | `convention-checker-prompt.md` | *(all files)* | Project rules — Grep-based |
+| **Refactoring Analyzer** | `refactoring-analyzer-prompt.md` | `[REFACTOR]` | Structure & Simplification |
 
 ## Reviewer Selection
 
-By default, run **all 5 reviewers**. If the user specifies a focus in natural language, select only the relevant reviewer(s):
+By default, run **all 4 reviewers**. If the user specifies a focus, select relevant reviewer(s):
 
 | User says | Run |
 |-----------|-----|
-| "bugs", "security", "safety", "architecture", "dependencies", "boundaries" | Code Reviewer only |
-| "API", "naming", "types", "DX" | API Reviewer only |
-| "conventions", "rules", "patterns" | Convention Checker only |
-| "simplify", "complexity", "duplication", "readability" | Code Simplifier only |
-| "structure", "responsibility", "module", "organization", "abstraction" | Structure Analyzer only |
+| "bugs", "security", "safety", "architecture", "dependencies" | Code Reviewer |
+| "API", "naming", "types", "DX" | API Reviewer |
+| "conventions", "rules", "patterns" | Convention Checker |
+| "simplify", "complexity", "duplication", "structure", "module" | Refactoring Analyzer |
 | "defects", "correctness" | Code + API + Convention |
-| "refactoring", "refactor", "maintainability" | Simplifier + Structure |
-| (no specific focus) | All 5 |
-
-Use judgment for ambiguous requests.
+| "refactoring", "refactor", "maintainability" | Refactoring Analyzer |
+| (no specific focus) | All 4 |
 
 ## Workflow
 
-### Step 1: Dispatch Reviewers
+### Step 1: Prepare Context
+
+Read these files:
+- `CLAUDE.md` — project overview
+- `.claude/rules/sd-refs-linker.md` — reference guide
+- Target's `package.json` — version (v12/v13)
+
+Based on version and target, read all applicable reference files (e.g., `sd-code-conventions.md`, `sd-solid.md`).
+
+Keep the collected conventions in memory — they will be inlined into each reviewer's prompt in Step 3.
+
+### Step 2: Explore (via sd-explore)
+
+Follow the **sd-explore** workflow to read all source files under the target.
+
+**sd-explore input:**
 
-Read the prompt template files from this skill's directory. Replace `[TARGET_PATH]` with the actual target path. Then dispatch using `Agent(general-purpose)`:
+- **Target path**: the review target directory
+- **Name**: `review`
+- **File patterns**: `**/*.ts`, `**/*.tsx` (exclude `node_modules`, `dist`)
+- **Analysis instructions**:
 
+"For each file:
+1. Write a 1-2 line summary of what it does
+2. Tag files that need deep review (~30-50% of files; a file can have multiple tags)
+
+Tag criteria:
+- [CORRECTNESS] — Unguarded null/! assertions, async races, DOM manipulation (SSR risks), resource lifecycle gaps, swallowed exceptions, mutable state for sync
+- [API] — Public exports, complex type signatures/generics/overloads, props/options interfaces, naming inconsistency
+- [REFACTOR] — File > 300 lines or function > 50 lines, deep nesting (> 3 levels), similar patterns across files, mixed abstraction levels, mixed responsibilities
+
+Output format:
 ```
-Agent(subagent_type=general-purpose, prompt=<filled template>)
+# Explore: [directory names]
+
+## File Summaries
+- `path/to/file.ts` — Brief description
+
+## Tagged Files
+### CORRECTNESS
+- `path/to/file.ts:42` — Suspected issue description
+### API
+- `path/to/file.ts` — Why this needs API review
+### REFACTOR
+- `path/to/file.ts` — Structural concern
 ```
 
-Run selected reviewers **in parallel** (multiple Agent calls in a single message).
+Files not listed under Tagged Files are considered clean. Do NOT add tags in File Summaries — Tagged Files is the single source of truth."
+
+### Step 3: Dispatch Reviewers (Parallel)
+
+Read each reviewer's prompt template. Replace:
+- `[CONVENTIONS]` → the conventions text collected in Step 1 (inline, not a file path)
+- `[EXPLORE_FILES]` → comma-separated list of explore output file paths
 
-### Step 2: Verify Findings
+Dispatch selected reviewers in parallel.
 
-After collecting results from all reviewers, **Read the actual code** for each finding and verify.
+### Step 4: Verify & Deduplicate
 
-**For defect findings (Code, API, Convention reviewers):**
+This is the **orchestrator-level** verification. Reviewers already self-verify, but findings can still be invalid or overlap.
 
-- **Valid**: the issue is real AND within scope → include in the report
-- **Invalid — self-contradicted**: the reviewer's own analysis shows the issue is mitigated (e.g., "exploitability is limited because..."). Drop it.
-- **Invalid — type-only**: reports a type definition as a runtime issue without showing actual runtime code that triggers it. Drop it.
-- **Invalid — out of scope**: the issue is about code outside the target path (e.g., how other packages use this code). Drop it.
-- **Invalid — duplicate**: another reviewer already reported the same issue. Keep only the one from the correct domain.
-- **Invalid — bikeshedding**: minor style preference on stable, well-commented code (magic numbers with clear comments, small interface field duplication, naming when used consistently). Drop it.
-- **Invalid — severity inflated**: downgrade or drop findings where the stated severity doesn't match the actual impact.
-- **Invalid — already handled**: handled elsewhere in the codebase (provide evidence)
-- **Invalid — intentional pattern**: by-design architectural decision
-- **Invalid — misread**: the reviewer misinterpreted the code
+**MANDATORY: Read actual code for EVERY finding.** For each finding, you MUST `Read` the file at the referenced location before deciding keep/drop. Do NOT rely on reviewer descriptions alone — verify against the actual code. A finding that was not verified by reading the source code CANNOT pass this step.
 
-**For refactoring findings (Simplifier, Structure reviewers):**
+**Deduplication**: If multiple reviewers flag the same code location, keep the finding under the most specific reviewer:
+- Convention violation + correctness concern → Convention Checker owns it
+- API issue + structural concern → API Reviewer owns it
+- When unclear, keep the one with stronger evidence
 
-**Check 1 — Scope**:
-- Is this about code structure? Not bugs, conventions, documentation, or performance → if not, drop (out of scope)
-- Is the issue within the target path? → if not, drop (out of target)
-- Already reported by another reviewer? → keep the better-scoped one (duplicate)
-- Minor style preference with no real structural impact? → drop (bikeshedding)
+**For defect findings (Code, API, Convention):**
 
-**Check 2 — Duplication reality** (for duplication findings):
-- Count actual duplicated lines. If < 30 lines total, drop — not worth extracting.
-- Compare side by side. If the "duplicates" have meaningful behavioral differences (different guards, parameters, error handling), drop — not true duplication.
-- Check if "similar types" are an intentional Input/Normalized pattern (optional props → required internal def with defaults applied, `children` → `cell` rename). If yes, drop — by design.
+Read the code, then drop if: self-contradicted, type-only (no runtime trigger), out of scope, duplicate, bikeshedding, severity inflated, already handled, intentional pattern, misread, tradeoff-negative.
 
-**Check 3 — Separation benefit** (for "too big", "mixed responsibilities", "mixed abstraction" findings):
-- Is the piece proposed for extraction < ~150 lines AND directly depends on the rest of the file (renders, calls, or shares state)? If yes, drop — splitting adds overhead without benefit.
-- Do all the abstractions serve a single cohesive domain concept (all functions called from one entry point, all types used together)? If yes, drop — it's cohesion, not mixing.
-- Would a realistic consumer reuse the extracted piece independently? If no, drop.
+**For refactoring findings:**
 
-**Check 4 — Not by design**: Is this an established pattern used consistently across the codebase? (Provider+Component, Factory+Product, Input/Output types) If yes, drop.
+Read the code at both/all referenced locations, then check:
 
-### Step 3: Invalid Findings Report
+- **Scope**: structural issue? within target? not a duplicate?
+- **Duplication reality**: count the actual shared lines (not the reviewer's estimate). < 30 lines → drop. Behavioral differences between the "duplicated" code → drop. Intentional Input/Normalized pattern → drop.
+- **Separation benefit**: < ~150 lines AND tightly coupled → drop. Single cohesive domain → drop. Not independently reusable → drop.
+- **By design**: established pattern used consistently → drop.
+- **Tradeoff-negative**: introduces more complexity than it removes → drop.
 
-Present only the **filtered findings** to the user:
+### Step 5: Report
+
+Present **both** invalid and valid findings:
 
 ```
 ## Review: <target-path>
 
 ### Invalid Findings
-[findings filtered out — grouped by rejection reason]
-```
+[grouped by rejection reason — brief, one line each]
 
-If there are **no valid findings**, report that the review found no actionable issues and end.
+### Valid Findings
+[full details for each verified finding]
+```
 
-### Step 4: User Confirmation
+If no valid findings, report that and end here.
 
-Present each verified finding to the user **one at a time**, ordered by severity (CRITICAL → WARNING → INFO → HIGH → MEDIUM → LOW).
+**If valid findings exist, you MUST proceed to Step 6. Do NOT ask the user whether to apply findings directly.**
 
-For each finding, explain:
-1. **What the problem is** — the current code behavior and why it's an issue
-2. **How it could be fixed** — possible solution approaches (if multiple exist, list them briefly)
-3. **Ask**: address this or skip?
+### Step 6: Brainstorm Handoff
 
-Collect only findings the user confirms. If the user skips all findings, report that and end.
+Invoke **sd-brainstorm** with all valid findings as context:
+_
+"Design fixes for the following review findings.
 
-### Step 5: Brainstorm Handoff
+**For each finding, you MUST:**
+1. Review it thoroughly — examine the code, understand the context, assess the real impact
+2. If any aspect is unclear or ambiguous, ask the user (one question at a time, per brainstorm rules)
+3. If a finding has low cost-benefit (adds complexity for marginal gain, pure style preference, scope too small), drop it. After triage, briefly list all dropped findings with one-line reasons (no user confirmation needed).
+4. For findings worth fixing, explore approaches and design solutions
 
-Pass only the **user-confirmed findings** to **sd-brainstorm**.
+Findings that survive your triage become the design scope. Apply your normal brainstorm process (gap review → approaches → design presentation) to the surviving findings as a group.
 
-Each finding includes: **source reviewer**, **file:line**, **evidence**, **issue**, and **suggestion**.
+<include all valid findings with their reviewer tag, file:line, problem description, and current code snippet>"
 
-sd-brainstorm will handle prioritization, grouping, approach exploration, and design.
+sd-brainstorm then owns the full cycle: triage (with user input as needed) → design.
 
 ## Common Mistakes
 
 | Mistake | Fix |
 |---------|-----|
-| Using git diff to limit review scope | Review ALL source files under target path |
-| Skipping verification step | Always verify reviewer findings against actual code |
-| Reporting unverified issues | Only include verified findings in final report |
-| Running all reviewers for focused requests | Match reviewer selection to user's request |
-| Reporting bugs as refactoring | Ask: "Is the behavior wrong?" If yes → defect, not refactoring |
-| Reporting style as refactoring | Ask: "Is this structural?" If no → lint, not refactoring |
-| Presenting valid findings as final report | Valid findings must be confirmed by user, then handed off to sd-brainstorm |
-| Dumping all findings at once for user confirmation | Present findings one at a time with problem explanation and solution approaches |
-
-## Completion Criteria
-
-Report invalid findings, then hand off all valid findings to sd-brainstorm. No code modifications during review.
+| Using git diff to limit scope | Review ALL source files under target |
+| Skipping verification | Always verify against actual code |
+| Running all reviewers for focused requests | Match selection to user's request |
+| Building per-reviewer files from explore results | Reviewers read explore files directly — no intermediate step |