@simplysm/sd-claude 13.0.74 → 13.0.76

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

@@ -37,7 +37,7 @@ async function readFileAsync() { ... } // Async suffix prohibited
 ## JSDoc Convention
 
 - Not enforced — omit when code is self-explanatory
-- When written, use Korean
+- When written, use English
 
 ## Re-export Restriction
 
@@ -50,8 +50,98 @@ async function readFileAsync() { ... } // Async suffix prohibited
 - Small packages (≤10 exports): `//` comments only
 - Always `export *` (wildcard), never explicit `export type { ... } from "..."`
 
+## `any` vs `unknown` vs Generics
+
+Choose based on **what you do with the value**:
+
+| Type | When | Key rule |
+|------|------|----------|
+| `any` | Value is **passed through** without property access | No `.prop`, no method calls, no narrowing |
+| `unknown` | Value's properties **will be accessed** but type is unknown | Must narrow with type guard before any access |
+| Generic `<T>` | **Input/output type relationship** must be preserved | Caller's type flows through to return type |
+
+```typescript
+// any — pure pass-through, no property access
+function logAndStore(value: any): void {
+  console.log(value);   // OK: no property access
+  storage.push(value);  // OK: just forwarding
+}
+
+// unknown — will access properties, must narrow first
+function getName(data: unknown): string {
+  if (typeof data === "object" && data !== null && "name" in data) {
+    return String((data as { name: unknown }).name);
+  }
+  throw new Error("No name property");
+}
+
+// Generic — input type preserved in output
+function wrapValue<T>(value: T): { value: T } {
+  return { value };
+}
+```
+
+**any vs Generic for pass-through:** If the function only forwards a value without accessing it AND the caller does not need type preservation in the return, use `any`. If the caller needs the same type back (input→output relationship), use a generic.
+
 ## Type Safety for Public APIs
 
 - 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)
-- Avoid `any` in public-facing types; use generics or specific union types instead
+- **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
+// Bad — consumers get no autocomplete, changes are invisible
+interface TableProps {
+  columns: Record<string, any>;
+  onRowClick: Function;
+}
+
+// Good — changes to ColumnDef break consumers at compile time
+interface TableProps<TRow> {
+  columns: ColumnDef<TRow>[];
+  onRowClick?: (row: TRow) => void;
+}
+```
+
+## Forced Type Casting Prohibition
+
+- **`as unknown as X` is prohibited** — dangerous escape hatch that silences real type errors
+- **`as X` must be avoided** unless there is no alternative — when tempted, try these fixes first:
+
+| Type error situation | Fix (instead of `as`) |
+|---------------------|-----------------------|
+| Missing properties | Add them to the interface |
+| Type too wide | Use generics to propagate correctly |
+| Unknown shape | Type guard: `if ("prop" in obj)`, `instanceof` |
+| Multiple shapes | Discriminated union or overload |
+| Wrong at source | Fix the root cause, not the usage site |
+
+```typescript
+// Bad — casting hides the real problem
+const admin = user as unknown as AdminUser;
+
+// Bad — lazy cast instead of proper narrowing
+const name = (event as any).target.name;
+
+// Good — fix parameter type at the source
+function getAdminDashboard(admin: AdminUser): string { ... }
+
+// Good — narrow unknown with type guard
+function getNameFromEvent(event: unknown): string {
+  if (typeof event === "object" && event !== null && "target" in event) {
+    const target = event.target;
+    if (typeof target === "object" && target !== null && "name" in target) {
+      return String(target.name);
+    }
+  }
+  throw new Error("Invalid event structure");
+}
+```
+
+## Boolean Prop Defaults
+
+- Name boolean props so their default value is `false`
+- Prefer `hide*`, `disable*` patterns where the feature is ON by default
+- This avoids double-negation in JSX: `hideX={false}` is clearer than `showX={true}` when both mean "show X"
+- Exception: inherent HTML attributes like `draggable` may default to `true`

package/claude/refs/sd-solid.md

@@ -48,6 +48,8 @@ All sub-components via dot notation only (`Parent.Child`).
 - Default `rem`, use `em` for text-relative sizing (e.g., Icon)
 - Use `clsx()` with semantic grouping + `twMerge()` for conflict resolution
 - Before modifying styles: Read existing class patterns of the same component
+- **Class strings inline**: Do not extract class strings into separate variables — write them directly in the JSX return
+- **`*.styles.ts` files**: Tailwind class strings must be wrapped with `clsx()` for IntelliSense support
 
 ## Application View Naming (`client-*`)
 

package/claude/refs/sd-workflow.md

@@ -6,7 +6,7 @@
 ## Problem-Solving Principles
 
 - **Root cause first**: When encountering errors or unexpected behavior, always investigate the root cause before attempting a fix. Do not apply workarounds, hacks, or surface-level patches.
-- **No band-aid fixes**: Avoid techniques like suppressing errors, adding defensive checks to hide symptoms, or bypassing validation. These mask the real problem and create technical debt.
+- **No band-aid fixes**: Avoid techniques like suppressing errors, adding defensive checks to hide symptoms, bypassing validation, or inflating timeout values. These mask the real problem and create technical debt.
 - **Consider refactoring**: If the root cause reveals a design flaw or structural issue, propose a refactoring approach rather than working around it. A proper fix — even if larger in scope — is better than a fragile workaround.
 - **Trace the full chain**: Follow the error or issue through the entire call chain (caller -> callee -> dependencies) to understand why it happens, not just where it happens.
 - **When uncertain, ask**: If the root cause is unclear or the fix requires significant changes, discuss with the user before proceeding. Present findings and options rather than silently applying a quick fix.
@@ -16,6 +16,7 @@
 - Before creating new files: Glob/Read similar existing files to check structure and patterns
 - Before modifying functions/classes: Read the file to understand existing code style
 - When unsure about API/method usage: Check signatures in source code
+- **Always search the local codebase first.** Do not search the web or external docs until you have confirmed the answer is not in local code.
 - **If confidence is low, ask the user instead of writing code**
 
 ## Memory Policy

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

@@ -39,6 +39,27 @@ If a referenced file or document cannot be found, **stop immediately and ask the
   - Any unsolicited observations about surrounding code quality
   - Only describe **what you changed** — nothing else
 
+### Analysis & Comparison
+
+- When analyzing, comparing, diffing, or auditing: **enumerate all items exhaustively**. Never provide a shallow summary — list every difference, even minor ones.
+  - Example: v12 vs v13 migration gap → list ALL API, type, pattern differences item by item
+
+### Direct Action Requests
+
+- 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
+
+**NEVER use `isolation: "worktree"` when calling the Agent tool.** This is an absolute rule with no exceptions.
+
+- 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.
+
 ## Asking Clarifying Questions
 
 When you need to ask the user a question, you MUST use the `AskUserQuestion` tool. Do NOT ask questions in plain text.

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

@@ -13,7 +13,7 @@ Determine the major version by the `version` field in `package.json`.
 
 | When                                             | Read this file                        |
 | ------------------------------------------------ | ------------------------------------- |
-| Writing or modifying code                        | `.claude/refs/sd-code-conventions.md` |
+| Writing, modifying, or reviewing code            | `.claude/refs/sd-code-conventions.md` |
 | Working with `.cache/` or Playwright screenshots | `.claude/refs/sd-directories.md`      |
 | Using `@simplysm/*` package APIs                 | `.claude/refs/sd-simplysm-docs.md`    |
 | Debugging, problem-solving, or planning approach | `.claude/refs/sd-workflow.md`         |

package/claude/sd-statusline.js

@@ -8,6 +8,8 @@ import { stdin } from "process";
 
 const STDIN_TIMEOUT_MS = 5000;
 const FETCH_TIMEOUT_MS = 3000;
+const CACHE_TTL_MS = 60_000; // 1 minute
+const CACHE_PATH = path.join(os.homedir(), ".claude", "usage-api-cache.json");
 
 //#endregion
 
@@ -75,16 +77,49 @@ function getOAuthToken() {
 }
 
 /**
- * Fetch Anthropic API usage information using OAuth token.
+ * Read cached usage data from local file.
+ * @returns {{ data: object, timestamp: number } | undefined}
+ */
+function readCache() {
+  try {
+    if (!fs.existsSync(CACHE_PATH)) return undefined;
+    const content = fs.readFileSync(CACHE_PATH, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Write usage data to local cache file.
+ * @param {object} data
+ */
+function writeCache(data) {
+  try {
+    fs.writeFileSync(CACHE_PATH, JSON.stringify({ data, timestamp: Date.now() }), "utf-8");
+  } catch {
+    // ignore write errors
+  }
+}
+
+/**
+ * Fetch Anthropic API usage information using OAuth token, with 1-minute cache.
  * @param {string} token - OAuth access token
+ * @param {string} version - Claude Code version
  * @returns {Promise<{
- *   seven_day?: {utilization?: number, resets_at?: string},  // 7-day usage
- *   daily?: {utilization?: number, resets_at?: string},       // daily usage
- *   five_hour?: {utilization?: number, resets_at?: string},   // 5-hour usage
- *   extra_usage?: {is_enabled?: boolean, monthly_limit?: number | null, used_credits?: number}  // extra usage
+ *   seven_day?: {utilization?: number, resets_at?: string},
+ *   daily?: {utilization?: number, resets_at?: string},
+ *   five_hour?: {utilization?: number, resets_at?: string},
+ *   extra_usage?: {is_enabled?: boolean, monthly_limit?: number | null, used_credits?: number}
  * } | undefined>}
  */
-async function fetchUsage(token) {
+async function fetchUsage(token, version) {
+  // Return cached data if still valid
+  const cache = readCache();
+  if (cache != null && (Date.now() - cache.timestamp) < CACHE_TTL_MS) {
+    return cache.data;
+  }
+
   try {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
@@ -93,6 +128,7 @@ async function fetchUsage(token) {
       headers: {
         "Authorization": `Bearer ${token}`,
         "anthropic-beta": "oauth-2025-04-20",
+        "User-Agent": `claude-code/${version}`,
       },
       signal: controller.signal,
     });
@@ -100,19 +136,24 @@ async function fetchUsage(token) {
     clearTimeout(timeout);
 
     if (!response.ok) {
-      return undefined;
+      // API failed — update timestamp to prevent retry for TTL duration
+      writeCache(cache?.data ?? {});
+      return cache?.data;
     }
 
     const data = await response.json();
 
-    // Validate response structure
     if (data == null || typeof data !== "object") {
-      return undefined;
+      writeCache(cache?.data ?? {});
+      return cache?.data;
     }
 
+    writeCache(data);
     return data;
   } catch {
-    return undefined;
+    // Network error — update timestamp to prevent retry for TTL duration
+    writeCache(cache?.data ?? {});
+    return cache?.data;
   }
 }
 
@@ -172,6 +213,7 @@ function formatTimeRemaining(isoDate) {
  * @property {{display_name?: string}} [model] - Model information
  * @property {{context_window_size?: number, remaining_context_tokens?: number, current_usage?: {input_tokens?: number, output_tokens?: number, cache_creation_input_tokens?: number, cache_read_input_tokens?: number}}} [context_window] - Context window information
  * @property {{tokens_used?: number, tokens_limit?: number}} [weekly_token_usage] - Weekly token usage (fallback)
+ * @property {string} [version] - Claude Code version
  */
 
 /**
@@ -212,7 +254,7 @@ async function main() {
   let extraUsage = "";
 
   if (token != null) {
-    const usageResponse = await fetchUsage(token);
+    const usageResponse = await fetchUsage(token, input.version ?? "unknown");
     if (usageResponse != null) {
       // Use daily or five_hour
       const dailyData = usageResponse.daily ?? usageResponse.five_hour;

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

@@ -31,9 +31,9 @@ Based on Phase 1 results, determine comparison targets and perspectives:
 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
 
-## Phase 3: Comparative Analysis & Report
+## Phase 3: Comparative Analysis
 
-Cross-compare Phase 1 and Phase 2 results to produce the report.
+Cross-compare Phase 1 and Phase 2 results and classify each item:
 
 | Priority | Criteria                                               |
 | -------- | ------------------------------------------------------ |
@@ -44,6 +44,25 @@ Cross-compare Phase 1 and Phase 2 results to produce the report.
 
 Each item includes: current name, recommended change, rationale (usage patterns per library).
 
+## Phase 4: Report & User Confirmation
+
+Present **Keep** items to the user as a summary.
+
+Then present each **P0/P1/P2** finding to the user **one at a time**, ordered by priority (P0 → P1 → P2).
+
+For each finding, explain:
+1. **What the problem is** — the current name and why it's misaligned or inconsistent
+2. **How it could be fixed** — recommended name(s) with rationale from surveyed libraries
+3. **Ask**: address this or skip?
+
+Collect only findings the user confirms. If the user skips all findings, report that and end.
+
+## Phase 5: Brainstorm Handoff
+
+Pass only the **user-confirmed findings** to **sd-brainstorm**.
+
+sd-brainstorm will handle prioritization, grouping, approach exploration, and design.
+
 ## Completion Criteria
 
-Present the report to the user. No code modifications.
+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.

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

@@ -14,12 +14,44 @@ 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)
+- Check out the current project state first (files, docs, recent commits). For deeper codebase exploration, consider using `sd-explore`.
 - 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
 - Focus on understanding: purpose, constraints, success criteria
 
+**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"];
+}
+```
+
+When proceeding with a section:
+
+1. **Read the main design** — understand goals, overall structure, and the target section's scope
+2. **Read actual code** — check the current codebase state for what previous sections have built. Reference the **actual code**, NOT previous section design documents. Code may have diverged from earlier designs during implementation.
+3. **Scope the brainstorm** — limit questions, gap review, approaches, and design presentation to the target section only. Do not re-question decisions already established in the main design.
+4. **Conflict detection** — if the main design's direction conflicts with the actual code state, alert the user and ask for direction before proceeding.
+5. After the design is complete, save as `docs/plans/YYYY-MM-DD-<topic>-section-N-design.md`
+6. Update the main design document: mark the section `[ ]` → `[x]` in the section plan
+7. Commit both files, then proceed to the normal **Next Steps Guide** (Path A/B)
+
 **Gap review loop:**
 
 When you think you've asked enough, **STOP and run a gap review before moving on.**
@@ -76,6 +108,63 @@ If your first gap review shows all ✅:
 - 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;
+}
+```
+
+**Section plan format** (append to existing design content as-is):
+
+```markdown
+---
+
+## Section Plan
+
+- [ ] Section 1: <name> — <scope summary>
+- [ ] Section 2: <name> — <scope summary> (after section 1)
+- [ ] Section 3: <name> — <scope summary> (after section 1, 2)
+```
+
+**Section guide** (shown instead of Path A/B, in user's configured language):
+
+```
+Design has been split into sections.
+
+Main design: docs/plans/YYYY-MM-DD-<topic>-design.md
+
+Section progress:
+- [ ] Section 1: <name>
+- [ ] Section 2: <name> (after section 1)
+- [ ] Section 3: <name> (after section 1, 2)
+
+Run each section in order:
+  sd-brainstorm docs/plans/YYYY-MM-DD-<topic>-design.md section 1
+
+After each section's brainstorm completes, you can choose Path A/B
+to run plan → plan-dev → check → commit.
+```
+
+Do NOT auto-proceed to any section.
+
 ## After the Design
 
 **Documentation:**

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

@@ -1,7 +1,6 @@
 ---
 name: sd-check
 description: "Typecheck, lint, test verification (explicit invocation only)"
-allowed-tools: Bash(npm run check:*), Bash(pnpm run check:*), Bash(yarn run check:*), Bash(npm run typecheck:*), Bash(pnpm run typecheck:*), Bash(yarn run typecheck:*), Bash(npm run lint:*), Bash(pnpm run lint:*), Bash(yarn run lint:*), Bash(npm run vitest:*), Bash(pnpm run vitest:*), Bash(yarn run vitest:*)
 ---
 
 # sd-check
@@ -34,19 +33,36 @@ Multiple types: `--type typecheck,lint`. No path = full project. No type = all c
 
 ## Workflow
 
-1. **Run** `$PM run check [path] [--type type]` (timeout: 600000)
-2. **All passed?** Report with actual output numbers → done
-3. **Errors?** Fix in priority order: typecheck → lint → test (fixes cascade)
-   - Test failures: **MUST** run `git log` to decide — update test or fix source
-   - **E2E test failures**: use Playwright MCP to investigate before fixing
-     1. `browser_navigate` to the target URL
-     2. `browser_snapshot` / `browser_take_screenshot` (save to `.tmp/playwright/`) to see page state
-     3. `browser_console_messages` for JS errors
-     4. `browser_network_requests` for failed API calls
-     5. Interact with the page following the test steps to reproduce the failure
-     6. Fix based on observed evidence, not guesswork
-   - Stuck after 2-3 attempts → recommend `/sd-debug`
-4. **Go to 1** — always re-run ALL checks after any fix
+```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"];
+}
+```
+
+**Run command:** `$PM run check [path] [--type type]` (timeout: 600000)
+
+**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
+- **E2E test failures**: use Playwright MCP to investigate before fixing
+  1. `browser_navigate` to the target URL
+  2. `browser_snapshot` / `browser_take_screenshot` (save to `.tmp/playwright/`) to see page state
+  3. `browser_console_messages` for JS errors
+  4. `browser_network_requests` for failed API calls
+  5. Interact with the page following the test steps to reproduce the failure
+  6. Fix based on observed evidence, not guesswork
 
 ## Rules
 

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

@@ -2,7 +2,6 @@
 name: sd-commit
 description: "Git commit with conventional messages (explicit invocation only)"
 argument-hint: "[all]"
-allowed-tools: Bash(git status:*), Bash(git add:*), Bash(git commit:*)
 model: haiku
 ---
 

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

@@ -196,25 +196,26 @@ You MUST complete each phase before proceeding to the next.
    - Issue actually resolved?
 
 4. **If Fix Doesn't Work**
-   - STOP
-   - Count: How many fixes have you tried?
-   - If < 3: Return to Phase 1, re-analyze with new information
-   - **If ≥ 3: STOP and question the architecture (step 5 below)**
-   - DON'T attempt Fix #4 without architectural discussion
 
-5. **If 3+ Fixes Failed: Question Architecture**
+   ```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)"];
+   }
+   ```
 
-   **Pattern indicating architectural problem:**
+   **Signs of architectural problem (≥3 failures):**
    - Each fix reveals new shared state/coupling/problem in different place
    - Fixes require "massive refactoring" to implement
    - Each fix creates new symptoms elsewhere
 
-   **STOP and question fundamentals:**
-   - Is this pattern fundamentally sound?
-   - Are we "sticking with it through sheer inertia"?
-   - Should we refactor architecture vs. continue fixing symptoms?
-
-   **Discuss with the user before attempting more fixes**
+   **Question fundamentals:** Is this pattern sound? Are we sticking with it through inertia? Should we refactor architecture vs. continue fixing symptoms?
 
    This is NOT a failed hypothesis - this is a wrong architecture.
 

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

@@ -0,0 +1,76 @@
+---
+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
+---
+
+# sd-explore
+
+You are an expert code analyst. Trace implementations across codebases and save structured analysis to file.
+
+## Target Selection
+
+**When invoked with `$ARGUMENTS`:**
+
+- 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
+
+**Analysis only — no code modifications.**
+
+## Output — Save to File
+
+**All analysis results MUST be saved to `.tmp/explore/`.** Do NOT dump the full analysis into the conversation.
+
+This prevents context loss from compaction and makes results available to subsequent skills/agents.
+
+### File Naming
+
+- **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`)
+
+### File Structure
+
+```markdown
+# {Target Name} — Explore
+
+> Analyzed: {target path}
+
+## Summary
+{1-3 sentence overview}
+
+## Architecture
+{Design patterns, layers, key abstractions}
+
+## Entry Points
+{APIs, components, commands — with file:line references}
+
+## Code Flow
+{Step-by-step execution traces}
+
+## Key Files
+{Essential files for understanding the target — with file:line references}
+
+## Dependencies
+{Internal and external dependencies}
+
+## Observations
+{Strengths, issues, opportunities}
+```
+
+### Workflow
+
+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
+
+**Example conversation output:**
+```
+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
+```