@simplysm/sd-claude 13.0.75 → 13.0.77

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

@@ -185,7 +185,7 @@ Report what was changed.
 | Ignoring existing docs/ structure     | If docs/ exists, update those files too                             |
 | Arbitrary section reorganization      | Follow index.ts `#region` structure                                 |
 | Missing import paths in examples      | Always: `import { X } from "@simplysm/..."`                         |
-| Writing in Korean                     | README must be in English                                           |
+| Writing in non-English languages      | README must be in English                                           |
 | Adding changelog sections             | Never add version history                                           |
 | Editing before reporting diff         | Always report ADDED/REMOVED/CHANGED and wait for confirmation       |
 | Destroying docs/ link format          | If README uses `[name](docs/file.md#anchor)`, preserve that pattern |

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

@@ -1,20 +1,25 @@
 ---
 name: sd-review
-description: "Comprehensive multi-perspective code review (explicit invocation only)"
+description: "Use when the user explicitly requests code review, refactoring analysis, or structural improvement. Covers correctness, safety, API design, conventions, complexity, duplication, and code structure. Explicit invocation only."
 ---
 
 # sd-review
 
 ## Overview
 
-Perform a multi-perspective code review of a package or specified path, producing a comprehensive report. **Analysis only — no code modifications.**
+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.
 
-Dispatches up to 3 reviewer agents in parallel using prompt templates. Each agent independently explores the codebase from its own perspective. Collects results, verifies findings against actual code, and compiles the final report.
+**Analysis only — no code modifications.**
+
+## Principles
+
+- **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 3 perspectives)
-- `/sd-review packages/solid focus on bugs` — selective review based on request
+- `/sd-review packages/solid` — full review (all perspectives)
+- `/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
 
 ## Target Selection
@@ -26,84 +31,152 @@ Dispatches up to 3 reviewer agents in parallel using prompt templates. Each agen
 
 ## Reviewer Perspectives
 
-| Reviewer | Prompt Template | Perspective |
-|----------|----------------|-------------|
-| **Code Reviewer** | `code-reviewer-prompt.md` | Correctness & Safety — bugs, security, logic errors |
-| **API Reviewer** | `api-reviewer-prompt.md` | Usability & DX — naming, types, consistency |
-| **Code Simplifier** | `code-simplifier-prompt.md` | Maintainability — complexity, duplication, 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 3 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" | Code Reviewer only |
-| "API", "naming", "types", "DX" | API Reviewer only |
-| "complexity", "duplication", "structure", "maintainability" | Code Simplifier only |
-| "bugs and API" | Code Reviewer + API Reviewer |
-| (no specific focus) | All 3 |
-
-Use judgment for ambiguous requests. When in doubt, run all 3.
+| "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" | 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.
 
-Read the prompt template files from this skill's directory. Replace `[TARGET_PATH]` with the actual target path. Then dispatch using `Agent(general-purpose)`:
+**sd-explore input:**
 
+- **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 2: Verify Findings
+### Step 3: Dispatch Reviewers (Parallel)
 
-After collecting results from all reviewers, **Read the actual code** for each finding and verify:
+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
 
-- **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 (bugs→Code, API→API, structure→Simplifier).
-- **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
+Dispatch selected reviewers in parallel.
 
-### Step 3: Final Report
+### Step 4: Verify & Deduplicate
 
-Compile only **verified findings** grouped by severity (not by reviewer):
+This is the **orchestrator-level** verification. Reviewers already self-verify, but findings can still be invalid or overlap.
 
-```
-## Review Report: <target-path>
+**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.
+
+**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
+
+**For defect findings (Code, API, Convention):**
+
+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.
 
-### CRITICAL
-[verified critical findings from all reviewers]
+**For refactoring findings:**
 
-### WARNING
-[verified warning findings from all reviewers]
+Read the code at both/all referenced locations, then check:
 
-### INFO
-[verified info findings from all reviewers]
+- **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.
+
+### Step 5: Report
+
+Present **both** invalid and valid findings:
 
-### Invalid Findings Summary (optional)
-[findings filtered out and why]
 ```
+## Review: <target-path>
+
+### Invalid Findings
+[grouped by rejection reason — brief, one line each]
+
+### Valid Findings
+[full details for each verified finding]
+```
+
+If no valid findings, report that and end here.
+
+**If valid findings exist, you MUST proceed to Step 6. Do NOT ask the user whether to apply findings directly.**
 
-Each finding includes: **source reviewer**, **file:line**, **evidence**, **issue**, and **suggestion**.
+### Step 6: Brainstorm Handoff
+
+Invoke **sd-brainstorm** with all valid findings as context:
+_
+"Design fixes for the following review findings.
+
+**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
+
+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.
+
+<include all valid findings with their reviewer tag, file:line, problem description, and current code snippet>"
+
+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 |
-
-## Completion Criteria
-
-Present the comprehensive report to the user. No code modifications.
+| 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 |

package/claude/skills/sd-review/api-reviewer-prompt.md

@@ -1,26 +1,26 @@
 # API Reviewer Prompt
 
-Template for `Agent(general-purpose)`. Fill in `[TARGET_PATH]`.
+Template for `Agent(general-purpose)`. Fill in `[CONVENTIONS]` and `[EXPLORE_FILES]`.
 
 ```
 You are reviewing a library's public API for developer experience (DX).
 Your question: "Would a first-time developer be confused or make mistakes using this API?"
 
-## Target
+## Context
 
-Review ALL source files at [TARGET_PATH].
+1. Review the following project conventions relevant to API design and naming:
 
-## Step 1: List all source files
+[CONVENTIONS]
 
-Use Glob to list all .ts files under the target path (exclude node_modules, dist).
+2. Read these explore result files: [EXPLORE_FILES]
+3. From the explore results' **Tagged Files → API** sections, collect all entries — these are your deep-read targets
 
-## Step 2: Map the public API surface
+## Step 1: Deep Review
 
-- Read index.ts to list all exports (types, functions, constants)
-- Read each exported type/interface/function definition
-- Read test files and consumer code to see actual usage patterns
-
-## Step 3: Find issues
+Read each file from the API tagged list. For each:
+1. Map the public API surface (exports, types, interfaces, function signatures)
+2. Verify suspected API issues from screening
+3. Look for additional issues
 
 Look for:
 - Naming consistency: same concept with different names, inconsistent prefix/suffix
@@ -29,38 +29,31 @@ Look for:
 - Defaults: basic use cases requiring excessive configuration
 - Pattern consistency: similar tasks requiring different patterns
 
-Important: Internal consistency takes priority over external standards.
-Before suggesting a naming change, verify the existing pattern across ALL similar
-components in the library. Do NOT suggest external conventions that break internal consistency.
+Internal consistency takes priority over external standards.
 
 Do NOT report:
 - Bugs, security, logic errors, race conditions
 - Code complexity, duplication, readability
-- Do NOT use WebSearch to compare with external libraries
-- TypeScript type system limitations that require workarounds (e.g., discriminated unions not narrowing due to template literals) — these are language constraints, not API design flaws
-- Naming preferences where the current name is used consistently across the codebase — consistency > personal preference
-- Minor field duplication in small interfaces (< 10 fields) where extraction adds indirection without real benefit
-
-## Step 4: Self-verify before reporting
+- TypeScript type system limitations (language constraints, not API flaws)
+- Naming preferences where current name is used consistently
+- Minor field duplication in small interfaces (< 10 fields)
 
-Before including ANY finding, verify:
+## Step 2: Self-verify
 
-1. **Severity check**: CRITICAL = developers WILL write wrong code because of this API. Not "could theoretically be confusing."
-2. **Consistency check**: Before suggesting a rename, search ALL usages. If the name is used consistently everywhere, it's NOT a finding.
-3. **Scope check**: Only report on the PUBLIC API of the target package. Do not report on how consumers should use it differently.
+1. CRITICAL = developers WILL write wrong code because of this API
+2. Before suggesting a rename, search ALL usages — consistent usage is NOT a finding
+3. Only report on PUBLIC API of the target
 
 **Quality over quantity: 3 verified findings > 10 maybe-findings.**
 
 ## Constraints
 
 - Analysis only. Do NOT modify any files.
-- Only report issues with real evidence from the code.
-- CRITICAL severity requires proof that the current API actively misleads — not just "could be better."
+- Only report issues with real evidence.
+- CRITICAL requires proof the API actively misleads.
 
 ## Output Format
 
-Use this exact format for every finding:
-
 ### [CRITICAL|WARNING|INFO] title
 
 - **File**: path/to/file.ts:42
@@ -68,23 +61,15 @@ Use this exact format for every finding:
 - **Issue**: what the problem is
 - **Suggestion**: how to improve it
 
-Severity:
-- CRITICAL: API misleads developers or types are insufficient for correct usage
-- WARNING: Significant DX friction — unnecessary complexity or inconsistency
-- INFO: Minor improvement — better naming or defaults exist
-
-Start your report with:
+Start with:
 
 ## API Review Results
 
 ### Summary
-- Files reviewed: N
+- Files deep-reviewed: N (list them)
 - Public API surface: brief description
 - Findings: X CRITICAL, Y WARNING, Z INFO
 
 ### Findings
 [findings here]
-
-### Positive Observations
-[what's already well-designed — keep these]
 ```

package/claude/skills/sd-review/code-reviewer-prompt.md

@@ -1,27 +1,25 @@
 # Code Reviewer Prompt
 
-Template for `Agent(general-purpose)`. Fill in `[TARGET_PATH]`.
+Template for `Agent(general-purpose)`. Fill in `[CONVENTIONS]` and `[EXPLORE_FILES]`.
 
 ```
 You are reviewing code for correctness and safety.
 Your question: "Does this code produce wrong results or pose risks?"
 
-## Target
+## Context
 
-Review ALL source files at [TARGET_PATH].
+1. Review the following project conventions relevant to correctness/safety:
 
-## Step 1: List all source files
+[CONVENTIONS]
 
-Use Glob to list all .ts files under the target path (exclude node_modules, dist).
-This is your review scope — every file in this list must be examined.
+2. Read these explore result files: [EXPLORE_FILES]
+3. From the explore results' **Tagged Files → CORRECTNESS** sections, collect all entries — these are your deep-read targets
 
-## Step 2: Understand the codebase
+## Step 1: Deep Review
 
-Read the project's CLAUDE.md for conventions. Then:
-- Read index.ts to map the module structure
-- Read each source file to understand logic flows, data transformations, error paths
-
-## Step 3: Find issues
+Read each file from the CORRECTNESS tagged list. For each:
+1. Verify the suspected issue from screening — is it real?
+2. Look for additional issues the screening might have missed
 
 Look for:
 - Bugs: null/undefined risks, off-by-one, wrong conditions, missing return values
@@ -29,37 +27,36 @@ Look for:
 - Race conditions: async ordering, shared state without synchronization
 - Resource leaks: uncleared subscriptions/listeners, unclosed handles
 - Error handling: swallowed exceptions, wrong fallbacks, missing propagation
+- Architectural defects: circular dependencies, boundary violations
 
 Do NOT report:
-- Naming consistency, API design, type quality (including `any` types)
-- Code complexity, duplication, readability improvements
+- Naming, API design, pure type quality
+- Code complexity, duplication, readability
 - Style preferences unless they cause actual bugs
-- Type definitions alone — a type allowing `stack?: string` is NOT a security issue unless the runtime code actually sends it unsanitized
-- Speculative future risks — "if config were changed to X, this would break" is not a finding
-- Issues in code OUTSIDE the target path (e.g., how other packages consume these types)
+- Type definitions alone without runtime trigger
+- Speculative future risks
+- Issues outside the reviewed files
 
-## Step 4: Self-verify before reporting
+**`any` type boundary**: Do NOT report `any` as a type quality issue. But DO report `any` if it enables a runtime crash (e.g., `(obj as any).method()` where `method` may not exist).
 
-Before including ANY finding, ask yourself:
+## Step 2: Self-verify
 
-1. **Is there runtime code here that actually triggers this?** (Not just a type definition)
-2. **Does the evidence contradict my conclusion?** (If you find a bound/limit that prevents the issue, drop it)
-3. **Is this within the target scope?** (Not about how other packages use this code)
+Before including ANY finding:
+1. Is there runtime code that actually triggers this?
+2. Does the evidence contradict my conclusion?
+3. Is this within scope?
 
-If you write "in practice this is unlikely because..." or "exploitability is limited because..." — that means it's NOT a real finding. Drop it.
+If you write "in practice this is unlikely because..." — drop it.
 
 **Quality over quantity: 3 verified findings > 10 maybe-findings.**
 
 ## Constraints
 
 - Analysis only. Do NOT modify any files.
-- Only report issues where the runtime behavior is demonstrably wrong or risky.
-- If your own analysis shows the issue is mitigated, do NOT report it.
+- Only report issues where runtime behavior is demonstrably wrong or risky.
 
 ## Output Format
 
-Use this exact format for every finding:
-
 ### [CRITICAL|WARNING|INFO] title
 
 - **File**: path/to/file.ts:42
@@ -72,12 +69,12 @@ Severity:
 - WARNING: Real problem that can occur in practice
 - INFO: Defensive improvement, low risk
 
-Start your report with:
+Start with:
 
 ## Code Review Results
 
 ### Summary
-- Files reviewed: N
+- Files deep-reviewed: N (list them)
 - Findings: X CRITICAL, Y WARNING, Z INFO
 
 ### Findings

package/claude/skills/sd-review/convention-checker-prompt.md

@@ -0,0 +1,61 @@
+# Convention Checker Prompt
+
+Template for `Agent(general-purpose)`. Fill in `[CONVENTIONS]` and `[EXPLORE_FILES]`.
+
+```
+You are checking code against project conventions.
+Your question: "Does this code violate any project-defined rules?"
+
+## Context
+
+1. Review the following project conventions (these are your Grep criteria):
+
+[CONVENTIONS]
+
+2. Read these explore result files: [EXPLORE_FILES]
+3. Collect ALL file paths from the **File Summaries** sections — these are your Grep scope
+
+## Step 1: Extract Grep-searchable patterns
+
+From the conventions, extract rules that can be checked via text pattern matching.
+
+Examples of Grep-searchable rules:
+- `as unknown as` — prohibited
+- `as any` — prohibited in public-facing types
+- `export * from` or `export { } from` outside `src/index.ts` — prohibited
+
+**Skip rules that require semantic understanding** (e.g., "Boolean props should default to false", "file names must be self-identifying"). Only check patterns that can be matched syntactically.
+
+## Step 2: Grep for each pattern
+
+For each prohibited pattern, run Grep across all files in scope.
+
+For patterns with justified exceptions (e.g., `as X` casts where no alternative exists), **read the surrounding code** to determine if the usage is justified per the convention's own exception clause. Report only unjustified matches.
+
+Do NOT skip or dismiss matches for these reasons:
+- "Widespread usage" is NOT an exception — it means widespread violation
+- "Codebase pattern" is NOT an exception — conventions define what's correct
+
+## Step 3: Report
+
+### [WARNING] title
+
+- **File**: path/to/file.ts:42
+- **Convention**: which rule from which convention
+- **Evidence**: the matching code (include snippet)
+- **Suggestion**: the fix recommended by the convention
+
+All violations are WARNING. Use CRITICAL only if the violation causes an immediate runtime bug.
+
+Start with:
+
+## Convention Check Results
+
+### Summary
+- Files checked: N
+- Conventions referenced: [list]
+- Violations found: N
+
+### Violations
+[findings here]
+```

package/claude/skills/sd-review/refactoring-analyzer-prompt.md

@@ -0,0 +1,92 @@
+# Refactoring Analyzer Prompt
+
+Template for `Agent(general-purpose)`. Fill in `[CONVENTIONS]` and `[EXPLORE_FILES]`.
+
+```
+You are analyzing code for structural improvement and simplification.
+Your question: "Can this code be simpler or better organized without changing its behavior?"
+
+## Context
+
+1. Review the following project conventions relevant to code structure:
+
+[CONVENTIONS]
+
+2. Read these explore result files: [EXPLORE_FILES]
+3. From the explore results' **Tagged Files → REFACTOR** sections, collect all entries — these are your deep-read targets
+
+## Step 1: Deep Review
+
+Read each file from the REFACTOR tagged list. For each:
+1. Verify suspected structural issues from screening
+2. Look for additional opportunities
+
+Look for:
+
+**Simplification:**
+- Unnecessary complexity: over-abstraction, needless indirection, complex generics
+- Duplication: same logic repeated across files, similar functions that could be unified
+- Readability: hard-to-follow control flow, unclear variable names, implicit behavior
+
+**Structure:**
+- Responsibility mixing: single module handling concerns that should be separate
+- Abstraction level mismatch: high-level orchestration mixed with low-level details
+- Module organization: related functionality scattered, or unrelated functionality grouped
+- Leaking abstractions: internal details exposed through public API
+- Coupling hotspots: changes that would cascade widely
+
+## CRITICAL — Scope boundaries
+
+Do NOT report:
+- Bugs, security, logic errors, race conditions → code review
+- Naming consistency, API design, type quality → API review
+- Convention violations → convention checker
+- Documentation gaps, style preferences, import ordering
+- Performance optimization (unless also a structural improvement)
+- Magic numbers with clear adjacent comments
+- Small interface duplication (< 10 fields) where extraction adds indirection
+- Issues outside the reviewed files
+
+**Test each finding:** "Is this about CODE STRUCTURE, or about something else?"
+
+## Step 2: Self-verify
+
+1. **Structure test**: genuinely structural? not a bug, convention, or doc issue?
+2. **Impact test**: would a developer actually struggle with this?
+3. **Intentional pattern**: used consistently across the codebase? → by-design, drop.
+4. **Separation benefit**: < ~150 lines AND tightly coupled? → splitting adds overhead, drop.
+5. **Duplication reality**: < 30 lines duplicated, or meaningful behavioral differences? → drop.
+
+**Quality over quantity: 3 verified structural findings > 10 mixed findings.**
+
+## Constraints
+
+- Analysis only. Do NOT modify any files.
+- Do NOT provide corrected code blocks. Describe issues in words only.
+- Only report structural issues with real evidence.
+
+## Output Format
+
+### [HIGH|MEDIUM|LOW] title
+
+- **File**: path/to/file.ts:42
+- **Evidence**: what you observed (include code snippet)
+- **Issue**: what the structural problem is
+- **Suggestion**: how to improve it (in words, not code)
+
+Impact levels:
+- HIGH: Major structural problem. Significantly harder to understand or modify safely.
+- MEDIUM: Notable concern. Unnecessary complexity or meaningful duplication.
+- LOW: Improvement opportunity. Cleaner structure exists but current is workable.
+
+Start with:
+
+## Refactoring Analysis Results
+
+### Summary
+- Files deep-reviewed: N (list them)
+- Findings: X HIGH, Y MEDIUM, Z LOW
+
+### Findings
+[findings here]
+```