@simplysm/sd-claude 13.0.74 → 13.0.76

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

@@ -18,6 +18,8 @@ Write comprehensive implementation plans assuming the engineer has zero context
 
 Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.
 
+When a task uses a codebase-specific utility (hook, helper, style token) or test pattern, add a one-line explanation of what it does and the source file path. Example: "`createMountTransition(open)` — manages mount/unmount with CSS transitions (`packages/solid/src/hooks/createMountTransition.ts`)". This applies to test utilities and patterns too — if a test uses a framework-specific pattern (e.g., SolidJS `createRoot` for reactive context), explain why that pattern is needed.
+
 **Announce at start:** "I'm using the sd-plan skill to create the implementation plan."
 
 **Save plans to:** `docs/plans/YYYY-MM-DD-<feature-name>.md`
@@ -31,6 +33,18 @@ Assume they are a skilled developer, but know almost nothing about our toolset o
 - "Run the tests and make sure they pass" - step
 - "Commit" - step
 
+**Step size limit:** If a single step produces more than ~30 lines of code, it is too large. Split it into multiple steps (e.g., "Define types and interfaces" → "Create context and hook" → "Implement provider component").
+
+**TDD means YAGNI per step:** Step 3 ("Write minimal implementation") must implement ONLY what's needed to pass Step 1's test — nothing more. If the component needs additional behavior (e.g., FIFO eviction, remove), that behavior goes in a SUBSEQUENT task with its own failing test first. Do NOT implement the full component in one task and then test it after the fact.
+
+## Task Ordering
+
+**Shared resources BEFORE consumers.** Tasks must be ordered so that every file a task imports already exists from a prior task.
+
+- Types, config, i18n entries → before components that use them
+- Provider → before components that call useX() hooks
+- If Task B imports from Task A's file → Task A must come first
+
 ## Plan Document Header
 
 **Every plan MUST start with this header:**
@@ -103,12 +117,30 @@ git commit -m "feat: add specific feature"
 ```
 ```
 
+## Test Requirement
+
+**Every task that creates or modifies logic MUST include a test.** No exceptions.
+
+- If the logic is testable with unit tests → write a vitest test file. This includes: pure functions, state management, timers/lifecycle logic (use `vi.useFakeTimers()`), event handlers, and state transitions.
+- If the logic is UI-only (visual rendering, Portal placement, CSS animation) → include a manual verification step with exact instructions ("Open the browser, click X, expect Y")
+- The **Files:** section must list the test file: `Test: exact/path/to/tests/file.spec.ts`
+- If you find yourself writing a task with no test step → **STOP and add one**
+
 ## Remember
 - Exact file paths always
+- Cross-check the design document's file structure — every file listed in the design MUST appear in the plan (create or modify)
 - Complete code in plan (not "add validation")
+- When modifying an existing file, show ALL necessary import additions/changes — not just the appended code
+- Code must compile cleanly — no unused imports or variables
 - Exact commands with expected output
 - DRY, YAGNI, TDD, frequent commits
 
+## 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
 
 After saving the plan, **commit the plan document to git** before proceeding.

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

@@ -37,7 +37,7 @@ All execution uses `Task(general-purpose)` for parallel execution.
 
 Independent tasks run as **parallel Task calls in a single message**. After implementers complete, spec and quality reviews run as **parallel Task calls**.
 
-**CRITICAL: Do NOT use `run_in_background: true`** — achieve parallelism by making multiple Task calls in a single message (foreground parallel). This ensures the orchestrator waits for all tasks to complete before proceeding to the next batch, and prevents Stop hooks from firing prematurely.
+**CRITICAL: Always launch parallel tasks as multiple Task calls in a single message (foreground parallel).** Never set `run_in_background: true` — it causes Stop hooks to fire prematurely. This rule applies regardless of permission mode (yolo, plan, etc.).
 
 ## The Process
 
@@ -104,7 +104,14 @@ digraph process {
     "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"];
-    "Task: final review for entire implementation" -> "Done";
+    "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"];
 }
 ```
 
@@ -216,9 +223,18 @@ You: Using sd-plan-dev to execute this plan.
 [Task: final review for entire implementation]
 Final reviewer: All requirements met, ready to merge
 
+[Run /simplify on all changed code]
+Simplify: extracted shared validation helper, removed 2 duplicate imports
+[typecheck + lint → pass]
+[Commit: refactor: simplify changed code]
+
 Done!
 ```
 
+## Verification-Only Tasks
+
+If a task is purely verification (no code changes — just running tests, typecheck, or manual checks), merge its checks into the batch integration check or final review rather than dispatching an implementer. These tasks exist in the plan for documentation purposes but don't need the full implementer → reviewer cycle.
+
 ## Batch Integration Check
 
 Between batches, run targeted verification on affected packages before starting the next batch.
@@ -232,6 +248,39 @@ $PM run lint [affected packages]
 
 This catches cross-task integration issues early — especially when the next batch depends on the current batch's output. Do NOT skip this even if individual task reviews passed.
 
+If typecheck or lint fails, treat the errors as review issues: re-dispatch the implementer(s) whose changes caused the failure with the error output. After fix, re-run the integration check. Do NOT start the next batch until integration passes.
+
+## Final Review Dispatch
+
+After all batches complete and pass integration checks, dispatch the final reviewer:
+
+1. Locate the original design document from `docs/plans/` — it shares the same date and topic as the plan file (e.g., plan `2026-03-04-dialog-confirm.md` → design `2026-03-04-dialog-confirm-design.md`)
+2. Fill `./final-review-prompt.md` with:
+   - The full text of the original design document
+   - The full text of the implementation plan
+   - Summaries of all completed tasks (commit SHAs, files changed, test results)
+3. Dispatch as `Task(general-purpose)`
+4. If the final reviewer returns **APPROVED** → done
+5. If the final reviewer returns **ISSUES**:
+   - For cross-task integration issues: create a fix task targeting specific files, run through implementer → review cycle
+   - For missing design requirements: create new implementation tasks and run through the full batch cycle
+   - Re-run final review after all fixes
+
+## Simplify
+
+After the final review passes, run `/simplify` to review all changed code for reuse, quality, and efficiency. This catches cross-task cleanup opportunities that individual reviewers miss.
+
+1. Orchestrator runs `/simplify` via the Skill tool
+2. If simplify made changes:
+   - Run typecheck/lint on affected packages
+   - If typecheck/lint fails → fix the issues and re-run typecheck/lint until it passes
+   - Commit simplify changes as a separate commit (`refactor: simplify changed code`)
+3. If simplify made no changes → skip to completion
+
+## Completion
+
+After simplify completes (or is skipped), report to the user: number of tasks completed, total files changed, and final review outcome.
+
 ## Red Flags
 
 **Never:**
@@ -246,6 +295,7 @@ This catches cross-task integration issues early — especially when the next ba
 - Accept "close enough" on spec compliance
 - Skip review loops (issue found → fix → re-review)
 - Skip batch integration checks between batches
+- Skip `/simplify` after final review
 - Use `run_in_background: true` on Task calls (use foreground parallel instead)
 
 **If implementer returns questions:**
@@ -273,5 +323,6 @@ This catches cross-task integration issues early — especially when the next ba
 **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-plan-dev/code-quality-reviewer-prompt.md

@@ -13,11 +13,9 @@ You are reviewing code quality for a completed implementation.
 ## Review Scope
 
 Use git diff to review only what changed:
-```
 
-git diff [BASE_SHA]..[HEAD_SHA]
+    git diff [BASE_SHA]..[HEAD_SHA]
 
-```
 BASE_SHA: [commit before task started]
 HEAD_SHA: [implementer's commit SHA from report]
 

package/claude/skills/sd-plan-dev/implementer-prompt.md

@@ -20,12 +20,20 @@ You are implementing Task [N]: [task name]
 
 If anything is unclear about requirements or approach, return your questions under a `## Questions` heading and STOP. Do not guess — do not implement.
 
+## Plan Deviations
+
+Plans may contain minor inaccuracies (wrong file paths, outdated API signatures, incorrect line numbers). Handle deviations by severity:
+
+- **Minor** (file path renamed, import path different, line numbers shifted): Adapt to the actual codebase and note the deviation in your report.
+- **Major** (API doesn't exist, approach fundamentally different, missing dependency): Return your questions under `## Questions` and STOP.
+
 ## While You Work
 
 If you encounter something unexpected mid-implementation (missing APIs, unexpected patterns, ambiguous behavior), **ask questions rather than guess**. Return your questions under `## Questions` and STOP. It's always OK to pause and clarify.
 
 ## Your Job
 
+0. **Before writing any code**: Read `.claude/refs/sd-code-conventions.md` and check `.claude/rules/sd-refs-linker.md` for additional refs relevant to the code you'll touch (e.g., `sd-solid.md` for SolidJS, `sd-orm.md` for ORM). Follow all project conventions — implementing a task does NOT exempt you from conventions.
 1. Implement exactly what the task specifies — nothing more, nothing less
 2. Write tests (follow TDD if the plan says to)
 3. Verify: tests pass, no type errors
@@ -35,7 +43,7 @@ If you encounter something unexpected mid-implementation (missing APIs, unexpect
    - **Discipline**: Nothing overbuilt (YAGNI)? Only what was requested?
    - **Testing**: Tests verify behavior (not implementation)? Comprehensive?
 5. Fix anything found in self-review
-6. Commit your work with a descriptive message (this is required for review)
+6. Commit using conventional commit format: `type(scope): description` (e.g., `feat(solid): add ConfirmDialog component`)
 7. Report back
 
 Work from: [directory path]
@@ -45,6 +53,7 @@ Work from: [directory path]
 When done, provide:
 - Commit SHA (from step 6)
 - Files created/modified (with brief description of changes)
+- Plan deviations (if any — what the plan said vs. what you did and why)
 - Test results
 - Self-review findings (if any were fixed)
 - Open concerns (if any)

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). Dispatches up to 5 reviewer agents in parallel, verifies findings against actual code, and compiles a unified report.
 
-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, 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.
 
 ## Usage
 
-- `/sd-review packages/solid` — full review (all 3 perspectives)
+- `/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 refactoring` — structural analysis only
 - `/sd-review` — if no argument, ask the user for the target path
 
 ## Target Selection
@@ -28,23 +33,28 @@ Dispatches up to 3 reviewer agents in parallel using prompt templates. Each agen
 
 | Reviewer | Prompt Template | Perspective |
 |----------|----------------|-------------|
-| **Code Reviewer** | `code-reviewer-prompt.md` | Correctness & Safety — bugs, security, logic errors |
+| **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 |
-| **Code Simplifier** | `code-simplifier-prompt.md` | Maintainability — complexity, duplication, structure |
+| **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 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 5 reviewers**. If the user specifies a focus in natural language, select only the relevant reviewer(s):
 
 | User says | Run |
 |-----------|-----|
-| "bugs", "security", "safety" | Code Reviewer only |
+| "bugs", "security", "safety", "architecture", "dependencies", "boundaries" | 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 |
+| "conventions", "rules", "patterns" | Convention Checker only |
+| "simplify", "complexity", "duplication", "readability" | Code Simplifier only |
+| "structure", "responsibility", "module", "organization", "abstraction" | Structure Analyzer only |
+| "defects", "correctness" | Code + API + Convention |
+| "refactoring", "refactor", "maintainability" | Simplifier + Structure |
+| (no specific focus) | All 5 |
 
-Use judgment for ambiguous requests. When in doubt, run all 3.
+Use judgment for ambiguous requests.
 
 ## Workflow
 
@@ -60,41 +70,73 @@ Run selected reviewers **in parallel** (multiple Agent calls in a single message
 
 ### Step 2: Verify Findings
 
-After collecting results from all reviewers, **Read the actual code** for each finding and verify:
+After collecting results from all reviewers, **Read the actual code** for each finding and verify.
+
+**For defect findings (Code, API, Convention reviewers):**
 
 - **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 — 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
 
-### Step 3: Final Report
+**For refactoring findings (Simplifier, Structure reviewers):**
 
-Compile only **verified findings** grouped by severity (not by reviewer):
+**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)
 
-```
-## Review Report: <target-path>
+**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.
 
-### CRITICAL
-[verified critical findings from all reviewers]
+**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.
 
-### WARNING
-[verified warning findings from all reviewers]
+**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.
 
-### INFO
-[verified info findings from all reviewers]
+### Step 3: Invalid Findings Report
 
-### Invalid Findings Summary (optional)
-[findings filtered out and why]
+Present only the **filtered findings** to the user:
+
+```
+## Review: <target-path>
+
+### Invalid Findings
+[findings filtered out — grouped by rejection reason]
 ```
 
+If there are **no valid findings**, report that the review found no actionable issues and end.
+
+### Step 4: User Confirmation
+
+Present each verified finding to the user **one at a time**, ordered by severity (CRITICAL → WARNING → INFO → HIGH → MEDIUM → LOW).
+
+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?
+
+Collect only findings the user confirms. If the user skips all findings, report that and end.
+
+### Step 5: Brainstorm Handoff
+
+Pass only the **user-confirmed findings** to **sd-brainstorm**.
+
 Each finding includes: **source reviewer**, **file:line**, **evidence**, **issue**, and **suggestion**.
 
+sd-brainstorm will handle prioritization, grouping, approach exploration, and design.
+
 ## Common Mistakes
 
 | Mistake | Fix |
@@ -103,7 +145,11 @@ Each finding includes: **source reviewer**, **file:line**, **evidence**, **issue
 | 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
 
-Present the comprehensive report to the user. No code modifications.
+Report invalid findings, then hand off all valid findings to sd-brainstorm. No code modifications during review.

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

@@ -12,10 +12,15 @@ Review ALL source files at [TARGET_PATH].
 
 ## Step 1: List all source files
 
-Use Glob to list all .ts files under the target path (exclude node_modules, dist).
+Use Glob to list all .ts/.tsx files under the target path (exclude node_modules, dist).
 
 ## Step 2: Map the public API surface
 
+Read the following reference files for project conventions:
+- `CLAUDE.md` — project overview and conventions
+- `.claude/rules/sd-refs-linker.md` — reference guide linking to detailed docs per topic (read relevant refs based on the target code)
+
+Then:
 - 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

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

@@ -12,12 +12,16 @@ Review ALL source files at [TARGET_PATH].
 
 ## Step 1: List all source files
 
-Use Glob to list all .ts files under the target path (exclude node_modules, dist).
+Use Glob to list all .ts/.tsx files under the target path (exclude node_modules, dist).
 This is your review scope — every file in this list must be examined.
 
 ## Step 2: Understand the codebase
 
-Read the project's CLAUDE.md for conventions. Then:
+Read the following reference files for project conventions:
+- `CLAUDE.md` — project overview and conventions
+- `.claude/rules/sd-refs-linker.md` — reference guide linking to detailed docs per topic (read relevant refs based on the target code)
+
+Then:
 - Read index.ts to map the module structure
 - Read each source file to understand logic flows, data transformations, error paths
 
@@ -29,10 +33,12 @@ 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 (reaching into another package's internals), wrong dependency direction (higher-level packages imported by lower-level ones)
 
 Do NOT report:
 - Naming consistency, API design, type quality (including `any` types)
-- Code complexity, duplication, readability improvements
+- Code complexity, duplication, readability improvements (handled by Code Simplifier)
+- Structural improvement suggestions (handled by Structure Analyzer)
 - 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

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

@@ -3,85 +3,92 @@
 Template for `Agent(general-purpose)`. Fill in `[TARGET_PATH]`.
 
 ```
-You are a maintainability analyst reviewing code structure.
-Your question: "Would a developer struggle to understand or modify this code?"
+You are analyzing code for structural simplification opportunities.
+Your question: "Can this code be simpler without changing its behavior?"
 
 ## Target
 
-Review ALL source files at [TARGET_PATH].
+Analyze ALL source files at [TARGET_PATH].
 
 ## Step 1: List all source files
 
-Use Glob to list all .ts files under the target path (exclude node_modules, dist).
+Use Glob to list all .ts/.tsx files under the target path (exclude node_modules, dist).
 
 ## Step 2: Understand the structure
 
+Read the following reference files for project conventions:
+- `CLAUDE.md` — project overview and conventions
+- `.claude/rules/sd-refs-linker.md` — reference guide linking to detailed docs per topic (read relevant refs based on the target code)
+
+Then:
 - Map module dependencies and abstraction layers
 - Compare whether similar-role files use consistent patterns
 - Identify complexity hotspots: deep nesting, long functions, complex conditionals
 
-## Step 3: Find issues
+## Step 3: Find refactoring opportunities
 
 Look for:
-- Unnecessary complexity: over-abstraction, needless indirection, complex generics
-- Duplication: same logic repeated, similar functions that could be unified
+- Unnecessary complexity: over-abstraction, needless indirection, complex generics that could be simpler
+- Duplication: same logic repeated across files, similar functions that could be unified
 - Readability: hard-to-follow control flow, unclear variable names, implicit behavior
-- Structure: too many files for simple concepts, or too many responsibilities in one file
-- Maintainability risk: changes that cascade widely, tightly coupled modules
-
-Do NOT report:
-- Bugs, security, logic errors → that's the code reviewer's job
-- Naming consistency, API design, type quality (including `any` types) → that's the API reviewer's job
-- Property shorthand (`uuid: uuid` vs `uuid`)
-- `else` after `return`
-- Comment style or JSDoc presence/absence
-- Import ordering or formatting preferences
-- Magic numbers that are well-explained by adjacent comments
-- Small interface duplication (< 10 fields) where extracting a base adds indirection without real benefit
-- Type placement across packages unless it causes concrete import/dependency issues
-- Issues in code OUTSIDE the target path (e.g., how other packages implement or consume these types)
+- File structure: too many files for simple concepts, or too many responsibilities in one file
+- Coupling: changes that would cascade widely, tightly coupled modules
+
+## CRITICAL — Scope boundaries
+
+Do NOT report ANY of the following. These are OUT OF SCOPE:
+- Bugs, security issues, logic errors, race conditions → that's code review
+- Naming consistency, API design, type quality (including `any` types) → that's API review
+- Code language violations (Korean comments, non-English strings) → that's lint
+- Documentation gaps (missing JSDoc, missing comments, undocumented behavior) → that's documentation
+- Style preferences (property shorthand, `else` after `return`, import ordering, formatting)
+- Performance optimization (unless the fix is ALSO a structural improvement)
+- Magic numbers with clear adjacent comments
+- Small interface duplication (< 10 fields) where extraction adds indirection without real benefit
+- Issues in code OUTSIDE the target path
+
+**Test each finding:** "Is this about CODE STRUCTURE, or about something else (bugs, conventions, docs, performance)?" If something else → drop it.
 
 ## Step 4: Self-verify before reporting
 
 Before including ANY finding:
 
-1. **Impact test**: Would a developer actually struggle with this? Or is it just "could be slightly cleaner"?
-2. **Scope check**: Is the issue IN the target code, or in how other code uses it?
-3. **Overlap check**: Is this already in the code reviewer's or API reviewer's domain? If yes, skip it.
+1. **Structure test**: Is this genuinely about code structure? Or is it a bug, convention, or documentation issue disguised as refactoring?
+2. **Impact test**: Would a developer actually struggle with this structure? Or is it just "could be slightly different"?
+3. **Scope check**: Is the issue IN the target code, or in how other code uses it?
 
-**Quality over quantity: 3 verified findings > 10 maybe-findings.**
+**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 and suggestions in words only.
-- Only report issues with real evidence from the code.
-- Focus on substance: structural issues that genuinely make the code hard to understand or modify.
-- Do NOT report findings that belong to other reviewers' scope.
+- Only report structural issues with real evidence from the code.
+- Focus on substance: structural problems that genuinely make the code harder to understand or modify.
 
 ## Output Format
 
 Use this exact format for every finding:
 
-### [CRITICAL|WARNING|INFO] title
+### [HIGH|MEDIUM|LOW] title
 
 - **File**: path/to/file.ts:42
 - **Evidence**: what you observed (include code snippet)
-- **Issue**: what the problem is
+- **Issue**: what the structural problem is
 - **Suggestion**: how to improve it (in words, not code)
 
-Severity:
-- CRITICAL: Major structural problem. Very hard to understand or modify safely.
-- WARNING: Significant maintainability concern. Unnecessary complexity or duplication.
-- INFO: Improvement opportunity. Cleaner approach exists but current code is workable.
+Impact levels:
+- HIGH: Major structural problem. Significantly harder to understand or modify safely.
+- MEDIUM: Notable structural concern. Unnecessary complexity or meaningful duplication.
+- LOW: Improvement opportunity. Cleaner structure exists but current code is workable.
 
 Start your report with:
 
-## Maintainability Review Results
+## Code Simplification Results
 
 ### Summary
 - Files reviewed: N
-- Findings: X CRITICAL, Y WARNING, Z INFO
+- Findings: X HIGH, Y MEDIUM, Z LOW
 
 ### Findings
 [findings here]

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

@@ -0,0 +1,64 @@
+# Convention Checker Prompt
+
+Template for `Agent(general-purpose)`. Fill in `[TARGET_PATH]`.
+
+```
+You are checking code against project conventions.
+Your question: "Does this code violate any project-defined rules?"
+
+## Target
+
+Check ALL source files at [TARGET_PATH].
+
+## Step 1: Read convention files
+
+Read `.claude/rules/sd-refs-linker.md` to find ALL convention files that apply to the target code. Then read each referenced convention file.
+
+At minimum, always read:
+- `.claude/refs/sd-code-conventions.md` — applies to all code
+
+Also read topic-specific refs based on the target code (e.g., `sd-solid.md` for SolidJS, `sd-orm.md` for ORM).
+
+## Step 2: Extract prohibited patterns
+
+From each convention file, extract rules that define prohibited or required patterns. Build a checklist of Grep-searchable patterns.
+
+Example from `sd-code-conventions.md`:
+- `as unknown as` — prohibited
+- `as any` — prohibited in public-facing types
+- `export * from` or `export { } from` outside `src/index.ts` — prohibited
+
+## Step 3: Grep for each pattern
+
+For each prohibited pattern, run a Grep search across all target files. Report every match.
+
+Do NOT skip, downgrade, or dismiss matches for any reason:
+- "Widespread usage" is NOT an exception — it means widespread violation
+- "No alternative" is NOT an exception — the convention file lists alternatives
+- "Codebase pattern" is NOT an exception — the convention defines what's correct, not current usage
+
+## Step 4: Report
+
+Use this exact format for every finding:
+
+### [WARNING] title
+
+- **File**: path/to/file.ts:42
+- **Convention**: which rule from which convention file
+- **Evidence**: the matching code (include snippet)
+- **Suggestion**: the fix recommended by the convention file
+
+All convention violations are WARNING severity. Use CRITICAL only if the violation causes an immediate runtime bug.
+
+Start your report with:
+
+## Convention Check Results
+
+### Summary
+- Files checked: N
+- Convention files referenced: [list]
+- Violations found: N
+
+### Violations
+[findings here]
+```