@simplysm/sd-claude 13.0.76 → 13.0.78

package/claude/refs/sd-code-conventions.md

@@ -19,6 +19,7 @@ Before using extension methods: Verify actual existence in `@simplysm/core-commo
 
 - Do not use `Async` suffix on function names — Async is the default
 - When both sync and async versions exist, use `Sync` suffix on the sync function
+- **Exception — extensions**: When adding an async version to an existing prototype (e.g., `Array`), follow the original naming convention. If the sync method already exists without a `Sync` suffix, use `Async` suffix for the async version.
 
 ```typescript
 // Good
@@ -27,8 +28,12 @@ function readFileSync() { ... }        // Sync version
 
 // Bad
 async function readFileAsync() { ... } // Async suffix prohibited
+
+// Exception — Array extension already has mapMany()
+Array.prototype.mapManyAsync = async function () { ... }  // OK
 ```
 
+
 ## File Naming
 
 - Auxiliary files (`types.ts`, `utils.ts`, etc.) must be prefixed with the main file name (e.g., `CrudSheet.types.ts`)
@@ -46,10 +51,14 @@ async function readFileAsync() { ... } // Async suffix prohibited
 
 ## index.ts Export Pattern
 
-- Large packages: `#region`/`#endregion` for sections + `//` for sub-groups
-- Small packages (≤10 exports): `//` comments only
+- Use `//` comments to group exports
 - Always `export *` (wildcard), never explicit `export type { ... } from "..."`
 
+## `#region` / `#endregion`
+
+- When splitting a large ts/tsx file has a bigger tradeoff than keeping it as-is, use `#region`/`#endregion` to organize sections within the file
+- Do not use in simple export files like index.ts
+
 ## `any` vs `unknown` vs Generics
 
 Choose based on **what you do with the value**:
@@ -87,7 +96,6 @@ function wrapValue<T>(value: T): { value: T } {
 
 - API changes must be detectable via **typecheck alone** — all affected usage sites must show compile errors
 - Public component props must support **IDE intellisense** (autocomplete, type hints)
-- **No `any` in public-facing types** — use generics or specific union types instead
 - **No `Record<string, any>` for structured props** — define explicit interfaces so consumers get autocomplete
 
 ```typescript

package/claude/refs/sd-solid.md

@@ -34,8 +34,17 @@
 
 All sub-components via dot notation only (`Parent.Child`).
 
-- Define `interface ParentComponent { Child: typeof ChildComponent }`
-- Assign `Parent.Child = ChildComponent;`
+- Export using `Object.assign` pattern:
+  ```ts
+  export const Select = Object.assign(SelectInnerComponent, {
+    Item: SelectItem,
+    Header: SelectHeader,
+    Action: SelectAction,
+    ItemTemplate: SelectItemTemplate,
+  });
+  ```
+- Do NOT declare a separate type or interface for the compound component (e.g., `SelectComponent`, `TabsComponent`)
+- Do NOT use type assertions on the export (e.g., `as SelectComponent`)
 - Don't export sub-components separately (export parent only)
 - UI elements → compound sub-components, non-rendering config (state, behavior, callbacks) → props
 

package/claude/rules/sd-claude-rules.md

@@ -35,7 +35,7 @@ If a referenced file or document cannot be found, **stop immediately and ask the
 - **Do NOT comment on code outside the requested change.** This includes:
   - Listing issues you noticed but did not fix
   - Describing what you "left alone" or "did not change"
-  - "참고", "suggestions", "by the way", "note", "what I left alone"
+  - "reference", "suggestions", "by the way", "note", "what I left alone"
   - Any unsolicited observations about surrounding code quality
   - Only describe **what you changed** — nothing else
 
@@ -48,17 +48,13 @@ If a referenced file or document cannot be found, **stop immediately and ask the
 
 - When the user provides a specific action (e.g., "rename X to Y", "delete this file"), **execute it directly**. Do not route through skill agents or sub-agent workflows for trivial operations.
 
-## Worktree Prohibition
+## Worktree Rules
 
-**NEVER use `isolation: "worktree"` when calling the Agent tool.** This is an absolute rule with no exceptions.
+All git worktrees MUST be created under the **`.worktrees/`** directory (project root). Never use `.claude/worktrees/` or any other location.
 
-- Do NOT create git worktrees unless the user explicitly says "worktree" (e.g., "create a worktree", "use a worktree").
-- Using `isolation: "worktree"` on Agent tool calls without explicit user instruction is **strictly prohibited**.
-- Worktrees leave behind directories and branches that clutter the repository and cause frustration.
-- If you need to run agents, run them **without** the `isolation` parameter.
-- If the user explicitly requests a worktree:
-  - Create it under the **`.worktree/`** directory (project root), NOT `.claude/worktrees/`.
-  - **After work is complete, you MUST delete the worktree and its branch** before finishing. No worktree may be left behind.
+- When using `isolation: "worktree"` on Agent tool calls, the worktree is created in `.worktrees/`.
+- **After work is complete, you MUST delete the worktree and its branch** before finishing. No worktree may be left behind.
+- Prefer using the **`/sd-worktree`** skill for worktree creation/deletion. It includes fixes for Claude Code's built-in worktree bugs.
 
 ## Asking Clarifying Questions
 

package/claude/sd-statusline.js

@@ -8,7 +8,7 @@ import { stdin } from "process";
 
 const STDIN_TIMEOUT_MS = 5000;
 const FETCH_TIMEOUT_MS = 3000;
-const CACHE_TTL_MS = 60_000; // 1 minute
+const CACHE_TTL_MS = 60_000; // 1 minutes
 const CACHE_PATH = path.join(os.homedir(), ".claude", "usage-api-cache.json");
 
 //#endregion
@@ -116,7 +116,7 @@ function writeCache(data) {
 async function fetchUsage(token, version) {
   // Return cached data if still valid
   const cache = readCache();
-  if (cache != null && (Date.now() - cache.timestamp) < CACHE_TTL_MS) {
+  if (cache != null && Date.now() - cache.timestamp < CACHE_TTL_MS) {
     return cache.data;
   }
 
@@ -127,8 +127,8 @@ async function fetchUsage(token, version) {
     const response = await fetch("https://api.anthropic.com/api/oauth/usage", {
       headers: {
         "Authorization": `Bearer ${token}`,
-        "anthropic-beta": "oauth-2025-04-20",
-        "User-Agent": `claude-code/${version}`,
+        "Accept": "application/json",
+        'anthropic-beta': 'oauth-2025-04-20'
       },
       signal: controller.signal,
     });
@@ -138,14 +138,14 @@ async function fetchUsage(token, version) {
     if (!response.ok) {
       // API failed — update timestamp to prevent retry for TTL duration
       writeCache(cache?.data ?? {});
-      return cache?.data;
+      return undefined;
     }
 
     const data = await response.json();
 
     if (data == null || typeof data !== "object") {
       writeCache(cache?.data ?? {});
-      return cache?.data;
+      return undefined;
     }
 
     writeCache(data);
@@ -153,7 +153,7 @@ async function fetchUsage(token, version) {
   } catch {
     // Network error — update timestamp to prevent retry for TTL duration
     writeCache(cache?.data ?? {});
-    return cache?.data;
+    return undefined;
   }
 }
 

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

@@ -8,32 +8,97 @@ model: sonnet
 
 ## Overview
 
-Compare a library/module's public API names against industry standards and review internal consistency, producing a standardization report. **Analysis only — no code modifications.**
+Compare a library/module's public API names against industry standards and review internal consistency, producing a standardization report. Uses **sd-explore** to extract the API surface, then dispatches research agents for industry comparison.
+
+**Analysis only — no code modifications.**
+
+## Principles
+
+- **Breaking changes are irrelevant**: Do NOT dismiss findings because renaming would cause a breaking change.
+- **Internal consistency first**: Internal naming consistency takes priority over external standards.
+
+## Usage
+
+- `/sd-api-name-review packages/solid` — full naming review
+- `/sd-api-name-review packages/orm-common` — review specific package
+- `/sd-api-name-review` — if no argument, ask the user for the target path
 
 ## Target Selection
 
-1. If args contain a path, use that path
-2. Otherwise, ask the user for the target path
+- With argument: review source code at the given path
+- Without argument: ask the user for the target path
+
+**Important:** Review ALL source files under the target path. Do not use git status or git diff to limit scope.
+
+## Workflow
+
+### 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 inform the analysis in later steps.
+
+### Step 2: API Extraction (via sd-explore)
+
+Follow the **sd-explore** workflow to extract the target's public API surface.
 
-## Phase 1: API Extraction
+**sd-explore input:**
 
-Use an Explore agent to extract the target's public API surface:
+- **Target path**: the review target directory
+- **Name**: `api-name-review`
+- **File patterns**: `**/*.ts`, `**/*.tsx` (exclude `node_modules`, `dist`)
+- **Analysis instructions**:
 
+"For each file, extract its public API surface:
 - All exported identifiers (functions, classes, types, constants, etc.)
 - Names and types of user-facing parameters/options/config
 - Naming pattern classification (prefixes, suffixes, verb/adjective/noun usage, abbreviations, etc.)
 
-## Phase 2: Industry Standard Research
+Output format:
+```
+# API Surface: [directory names]
 
-Based on Phase 1 results, determine comparison targets and perspectives:
+## Exports
+- `path/to/file.ts` — `exportName`: type (function/class/type/const), signature summary
+
+## Naming Patterns
+- Pattern: description (e.g., 'create-' prefix for factory functions)
+- Examples: list of identifiers using this pattern
+```
+"
+
+### Step 3: Industry Standard Research
+
+Based on Step 2 results:
 
 1. Identify **recurring naming patterns** from the extracted API
 2. Determine the target's domain and tech stack to **select comparable libraries**
-3. Use **parallel agents** to web-search/fetch official docs for each library, investigating naming conventions for the same pattern categories
+3. Dispatch **parallel agents** to web-search/fetch official docs for each comparable library, investigating naming conventions for the same pattern categories
+
+Each research agent receives:
+
+```
+Research naming conventions in [library name] for these pattern categories:
+[list of patterns from Step 2]
+
+For each pattern, document:
+- What naming convention the library uses
+- Specific examples from the API
+- Any documented rationale for the convention
+
+Write results to: .tmp/api-name-review/research-{library_name}.md
+```
 
-## Phase 3: Comparative Analysis
+### Step 4: Comparative Analysis & Verification
 
-Cross-compare Phase 1 and Phase 2 results and classify each item:
+Cross-compare Step 2 (API surface) and Step 3 (industry research) results.
+
+Classify each naming pattern:
 
 | Priority | Criteria                                               |
 | -------- | ------------------------------------------------------ |
@@ -42,9 +107,11 @@ Cross-compare Phase 1 and Phase 2 results and classify each item:
 | **P2**   | Better industry term exists (optional)                 |
 | **Keep** | Already aligned with standards                         |
 
-Each item includes: current name, recommended change, rationale (usage patterns per library).
+**MANDATORY: Read actual code for EVERY finding.** For each finding, `Read` the file at the referenced location before finalizing. Do NOT rely on explore descriptions alone — verify against the actual code.
+
+Each finding includes: current name, recommended change, rationale (usage patterns per library).
 
-## Phase 4: Report & User Confirmation
+### Step 5: Report & User Confirmation
 
 Present **Keep** items to the user as a summary.
 
@@ -57,12 +124,31 @@ For each finding, explain:
 
 Collect only findings the user confirms. If the user skips all findings, report that and end.
 
-## Phase 5: Brainstorm Handoff
+### Step 6: Brainstorm Handoff
+
+Invoke **sd-brainstorm** with all user-confirmed findings as context:
+
+_
+"Design naming changes 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.
 
-Pass only the **user-confirmed findings** to **sd-brainstorm**.
+<include all confirmed findings with their priority, file:line, current name, recommended name, and rationale>"
 
-sd-brainstorm will handle prioritization, grouping, approach exploration, and design.
+sd-brainstorm then owns the full cycle: triage (with user input as needed) → design.
 
-## Completion Criteria
+## Common Mistakes
 
-Report Keep items, confirm P0/P1/P2 findings with user one by one, then hand off confirmed findings to sd-brainstorm. No code modifications during review.
+| Mistake | Fix |
+|---------|-----|
+| Using git diff to limit scope | Review ALL source files under target |
+| Skipping context preparation | Always read conventions and refs before analysis |
+| Skipping verification | Always verify findings against actual code |
+| Dismissing findings due to breaking changes | Breaking changes are irrelevant — report the naming issue |
+| Not writing research results to files | Research agents MUST write to disk — prevents context bloat |

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

@@ -14,7 +14,7 @@ Start by understanding the current project context, then ask questions one at a
 ## The Process
 
 **Understanding the idea:**
-- Check out the current project state first (files, docs, recent commits). For deeper codebase exploration, consider using `sd-explore`.
+- Check out the current project state first (files, docs, recent commits).
 - Ask questions one at a time to refine the idea
 - Prefer multiple choice questions when possible, but open-ended is fine too
 - Only one question per message - if a topic needs more exploration, break it into multiple questions
@@ -22,24 +22,16 @@ Start by understanding the current project context, then ask questions one at a
 
 **When a main design document is provided as context:**
 
-```dot
-digraph sub_design {
-    has_main [label="Main design with\nsection plan in context?" shape=diamond];
-    section_specified [label="Section specified?" shape=diamond];
-    prereqs_ok [label="Prerequisites\ncomplete?" shape=diamond];
-    normal [label="Normal brainstorm" shape=box];
-    show_progress [label="Show section progress\nAsk which section\n(suggest next incomplete)" shape=box];
-    warn [label="Warn prerequisites incomplete\nAsk: proceed anyway\nor complete first?" shape=box];
-    proceed [label="Proceed with section" shape=box];
-
-    has_main -> normal [label="no"];
-    has_main -> section_specified [label="yes"];
-    section_specified -> show_progress [label="no"];
-    section_specified -> prereqs_ok [label="yes"];
-    prereqs_ok -> proceed [label="yes"];
-    prereqs_ok -> warn [label="no"];
-    warn -> proceed [label="user: proceed"];
-}
+```mermaid
+flowchart TD
+    A{"Main design with<br>section plan in context?"}
+    A -->|no| B[Normal brainstorm]
+    A -->|yes| C{Section specified?}
+    C -->|no| D["Show section progress<br>Ask which section<br>(suggest next incomplete)"]
+    C -->|yes| E{"Prerequisites<br>complete?"}
+    E -->|yes| F[Proceed with section]
+    E -->|no| G["Warn prerequisites incomplete<br>Ask: proceed anyway<br>or complete first?"]
+    G -->|"user: proceed"| F
 ```
 
 When proceeding with a section:
@@ -101,37 +93,31 @@ If your first gap review shows all ✅:
 - Present options conversationally with your recommendation and reasoning
 - Lead with your recommended option and explain why
 
-**Presenting the design:**
-- Once you believe you understand what you're building, present the design
-- Break it into sections of 200-300 words
-- Ask after each section whether it looks right so far
-- Cover: architecture, components, data flow, error handling, testing
-- Be ready to go back and clarify if something doesn't make sense
-
 **Scale assessment:**
 
-After the design presentation is complete, assess scale (file count, logic complexity, number of distinct subsystems, scope of impact):
-
-```dot
-digraph scale {
-    assess [label="Assess design scale" shape=diamond];
-    manageable [label="Proceed to\nAfter the Design\n(Path A/B)" shape=box];
-    propose [label="Propose to user:\nproceed as-is OR\nsplit into sections" shape=box];
-    user_choice [label="User choice?" shape=diamond];
-    division [label="Propose 2-3 section\ndivision approaches\n(by feature/layer/dependency)" shape=box];
-    save [label="Append section plan\nto design doc\nSave + commit" shape=box];
-    guide [label="Show section guide\nBrainstorm ENDS" shape=box];
-
-    assess -> manageable [label="manageable"];
-    assess -> propose [label="large"];
-    propose -> user_choice;
-    user_choice -> manageable [label="proceed as-is"];
-    user_choice -> division [label="split"];
-    division -> save [label="user selects"];
-    save -> guide;
-}
+After the approach is selected, assess scale (file count, logic complexity, number of distinct subsystems, scope of impact):
+
+```mermaid
+flowchart TD
+    A{"Assess design scale"}
+    A -->|manageable| B["Proceed to<br>After the Design<br>(Path A/B)"]
+    A -->|large| C["Propose to user:<br>proceed as-is OR<br>split into sections"]
+    C --> D{"User choice?"}
+    D -->|"proceed as-is"| B
+    D -->|split| E["Propose 2-3 section<br>division approaches<br>(by feature/layer/dependency)"]
+    E -->|"user selects"| F["Append section plan<br>to design doc<br>Save + commit"]
+    F --> G["Show section guide<br>Brainstorm ENDS"]
 ```
 
+**How to present the split proposal:**
+
+When proposing the split to the user, you MUST clearly explain what "section split" means:
+
+- **Section split** = the design document is divided into sections, and each section goes through its own **separate brainstorm → plan → plan-dev → check → commit cycle**.
+- This is NOT about implementation phasing (doing some changes before others). It's about breaking the design work itself into independently deliverable chunks.
+- Explain: "Splitting into sections means each section goes through its own brainstorm → plan → plan-dev cycle. Complete and commit one section before moving to the next."
+- Contrast with: "Proceeding as-is means this single design document goes straight to plan → plan-dev."
+
 **Section plan format** (append to existing design content as-is):
 
 ```markdown
@@ -226,5 +212,4 @@ You can start from any step or skip steps as needed.
 - **Multiple choice preferred** - Easier to answer than open-ended when possible
 - **YAGNI ruthlessly** - Remove unnecessary features from all designs
 - **Explore alternatives** - Always propose 2-3 approaches before settling
-- **Incremental validation** - Present design in sections, validate each
 - **Be flexible** - Go back and clarify when something doesn't make sense

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

@@ -33,26 +33,24 @@ Multiple types: `--type typecheck,lint`. No path = full project. No type = all c
 
 ## Workflow
 
-```dot
-digraph check_workflow {
-    "Run check" [shape=box];
-    "All passed?" [shape=diamond];
-    "Report results → done" [shape=box];
-    "Fix errors\n(typecheck → lint → test)" [shape=box];
-    "Stuck after 2-3 tries?" [shape=diamond];
-    "Recommend /sd-debug" [shape=box];
-
-    "Run check" -> "All passed?";
-    "All passed?" -> "Report results → done" [label="yes"];
-    "All passed?" -> "Fix errors\n(typecheck → lint → test)" [label="no"];
-    "Fix errors\n(typecheck → lint → test)" -> "Stuck after 2-3 tries?";
-    "Stuck after 2-3 tries?" -> "Run check" [label="no"];
-    "Stuck after 2-3 tries?" -> "Recommend /sd-debug" [label="yes"];
-}
+```mermaid
+flowchart TD
+    A[Run check] --> B{All passed?}
+    B -->|yes| C[Report results → done]
+    B -->|no| D["Fix errors (typecheck → lint → test)"]
+    D --> E{Stuck after 2-3 tries?}
+    E -->|no| A
+    E -->|yes| F[Recommend /sd-debug]
 ```
 
 **Run command:** `$PM run check [path] [--type type]` (timeout: 600000)
 
+- **Output capture:** Bash truncates long output. Always redirect to a file and read it:
+  ```bash
+  mkdir -p .tmp && $PM run check [path] [--type type] > .tmp/check-output.txt 2>&1; echo "EXIT:$?"
+  ```
+  Then use the **Read** tool on `.tmp/check-output.txt` to see the full result. Check `EXIT:0` for success or non-zero for failure.
+
 **Fixing errors:**
 - **Before fixing any code**: Read `.claude/refs/sd-code-conventions.md` and check `.claude/rules/sd-refs-linker.md` for additional refs relevant to the affected code area (e.g., `sd-solid.md` for SolidJS, `sd-orm.md` for ORM). Fixing errors does NOT exempt you from following project conventions.
 - Test failures: **MUST** run `git log` to decide — update test or fix source

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

@@ -49,7 +49,7 @@ type(scope): short description
 | ------------- | ---------------------------------------------------------------------------- |
 | `type`        | `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `build`, `style`, `perf` |
 | `scope`       | package name or area (e.g., `solid`, `core-common`, `orm-node`)              |
-| `description` | written in the system's configured language, imperative, lowercase, no period at end |
+| `description` | English, imperative, lowercase, no period at end |
 
 Examples:
 
@@ -57,8 +57,6 @@ Examples:
 - `fix(orm-node): handle null values in bulk insert`
 - `docs: update README with new API examples`
 
-> **Note:** The examples above are in English for reference only. The actual description MUST be written in the system's configured language.
-
 Use a HEREDOC for multi-line messages when needed.
 
 ## Execution

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

@@ -197,17 +197,11 @@ You MUST complete each phase before proceeding to the next.
 
 4. **If Fix Doesn't Work**
 
-   ```dot
-   digraph fix_failure_loop {
-       "Fix failed?" [shape=diamond];
-       "Attempts < 3?" [shape=diamond];
-       "Phase 1: Re-analyze\nwith new information" [shape=box];
-       "STOP: Question Architecture\n→ Discuss with user first" [shape=box];
-
-       "Fix failed?" -> "Attempts < 3?";
-       "Attempts < 3?" -> "Phase 1: Re-analyze\nwith new information" [label="yes"];
-       "Attempts < 3?" -> "STOP: Question Architecture\n→ Discuss with user first" [label="no (≥3)"];
-   }
+   ```mermaid
+   flowchart TD
+       A{"Fix failed?"} --> B{"Attempts < 3?"}
+       B -->|yes| C["Phase 1: Re-analyze<br>with new information"]
+       B -->|"no (≥3)"| D["STOP: Question Architecture<br>→ Discuss with user first"]
    ```
 
    **Signs of architectural problem (≥3 failures):**

package/claude/skills/sd-debug/condition-based-waiting.md

@@ -8,17 +8,11 @@ Flaky tests often guess at timing with arbitrary delays. This creates race condi
 
 ## When to Use
 
-```dot
-digraph when_to_use {
-    "Test uses setTimeout/sleep?" [shape=diamond];
-    "Testing timing behavior?" [shape=diamond];
-    "Document WHY timeout needed" [shape=box];
-    "Use condition-based waiting" [shape=box];
-
-    "Test uses setTimeout/sleep?" -> "Testing timing behavior?" [label="yes"];
-    "Testing timing behavior?" -> "Document WHY timeout needed" [label="yes"];
-    "Testing timing behavior?" -> "Use condition-based waiting" [label="no"];
-}
+```mermaid
+flowchart TD
+    A{"Test uses setTimeout/sleep?"} -->|yes| B{"Testing timing behavior?"}
+    B -->|yes| C[Document WHY timeout needed]
+    B -->|no| D[Use condition-based waiting]
 ```
 
 **Use when:**

package/claude/skills/sd-debug/root-cause-tracing.md

@@ -8,19 +8,12 @@ Bugs often manifest deep in the call stack (git init in wrong directory, file cr
 
 ## When to Use
 
-```dot
-digraph when_to_use {
-    "Bug appears deep in stack?" [shape=diamond];
-    "Can trace backwards?" [shape=diamond];
-    "Fix at symptom point" [shape=box];
-    "Trace to original trigger" [shape=box];
-    "BETTER: Also add defense-in-depth" [shape=box];
-
-    "Bug appears deep in stack?" -> "Can trace backwards?" [label="yes"];
-    "Can trace backwards?" -> "Trace to original trigger" [label="yes"];
-    "Can trace backwards?" -> "Fix at symptom point" [label="no - dead end"];
-    "Trace to original trigger" -> "BETTER: Also add defense-in-depth";
-}
+```mermaid
+flowchart TD
+    A{"Bug appears deep in stack?"} -->|yes| B{"Can trace backwards?"}
+    B -->|yes| C[Trace to original trigger]
+    B -->|"no - dead end"| D[Fix at symptom point]
+    C --> E["BETTER: Also add defense-in-depth"]
 ```
 
 **Use when:**
@@ -142,26 +135,18 @@ Runs tests one-by-one, stops at first polluter. See script for usage.
 
 ## Key Principle
 
-```dot
-digraph principle {
-    "Found immediate cause" [shape=ellipse];
-    "Can trace one level up?" [shape=diamond];
-    "Trace backwards" [shape=box];
-    "Is this the source?" [shape=diamond];
-    "Fix at source" [shape=box];
-    "Add validation at each layer" [shape=box];
-    "Bug impossible" [shape=doublecircle];
-    "NEVER fix just the symptom" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
-
-    "Found immediate cause" -> "Can trace one level up?";
-    "Can trace one level up?" -> "Trace backwards" [label="yes"];
-    "Can trace one level up?" -> "NEVER fix just the symptom" [label="no"];
-    "Trace backwards" -> "Is this the source?";
-    "Is this the source?" -> "Trace backwards" [label="no - keeps going"];
-    "Is this the source?" -> "Fix at source" [label="yes"];
-    "Fix at source" -> "Add validation at each layer";
-    "Add validation at each layer" -> "Bug impossible";
-}
+```mermaid
+flowchart TD
+    A(["Found immediate cause"]) --> B{"Can trace one level up?"}
+    B -->|yes| C["Trace backwards"]
+    B -->|no| D["NEVER fix just the symptom"]:::danger
+    C --> E{"Is this the source?"}
+    E -->|"no - keeps going"| C
+    E -->|yes| F["Fix at source"]
+    F --> G["Add validation at each layer"]
+    G --> H(("Bug impossible"))
+
+    classDef danger fill:#f00,color:#fff
 ```
 
 **NEVER fix just where the error appears.** Trace back to find the original trigger.