moicle 2.3.1 → 3.0.0

package/assets/skills/fix/root-cause/SKILL.md

@@ -1,276 +0,0 @@
----
-name: fix-root-cause
-description: Deep bug investigation workflow for hard-to-trace errors. Systematic root cause analysis — no guessing, no blind fixes. Use when user says "deep debug", "deep-debug", "trace bug", "find root cause", "hard bug", "investigate bug".
----
-
-# Deep Bug Investigation
-
-For bugs that have been "fixed" multiple times and keep coming back, intermittent bugs, or errors deep inside vendor code. **Do not guess** — trace step by step.
-
-## When to use this skill
-
-- ✅ Same bug returns after multiple "fixes"
-- ✅ "Sometimes works, sometimes doesn't" — likely hidden state
-- ✅ Error inside vendor / framework internals
-- ✅ Local vs production behavior differs
-- ✅ Race condition / concurrency suspected
-- ❌ Bug is well understood, just needs a fix → `/fix-hotfix`
-- ❌ Production is down with user impact → `/fix-incident` first, then this skill
-
----
-
-## Workflow
-
-```
-COLLECT → VERIFY → TRACE → ROOT CAUSE → CHECK HIDDEN STATE → FIX → VERIFY
-```
-
-**Time budget:** if you've traced for >2 hours with no convergence → stop, write down what you know, ask a teammate. Rabbit holes are real.
-
----
-
-## Step 1: COLLECT — capture evidence exactly
-
-Record **verbatim**, do not interpret:
-
-- Exact error message (copy-paste, don't paraphrase)
-- Stack trace: file, line, full call chain
-- Affected environment (prod / staging / local)
-- Frequency: always / intermittent / specific input / specific user
-- Timing: started exactly when? aligns with a deploy / cron / data change?
-
-### Gate
-- [ ] Error captured verbatim
-- [ ] Stack trace captured (or noted absent)
-- [ ] Frequency known
-- [ ] Timing noted (helps narrow "what changed")
-
----
-
-## Step 2: VERIFY — running code = local code?
-
-Do NOT assume prod = local.
-
-- Identify the deployed commit
-- `git diff` deployed vs local
-- If they differ → read the deployed version before reasoning further
-- Container / image involved? Verify the image tag, not just the source
-
-### Gate
-- [ ] Deployed commit identified
-- [ ] Local checkout matches OR differences understood
-
----
-
-## Step 3: TRACE — entry to failure, every step
-
-The single most important step. Skip nothing.
-
-### 3a. Entry → error line
-- Where does the request / event / job enter? (route, listener, cron, queue handler)
-- Which function calls which? Follow stack trace exactly
-- How does data flow between layers?
-
-### 3b. Where does faulty data come from?
-- Created locally or loaded from DB / API / cache / session?
-- Goes through serialize / deserialize?
-- Goes through any transform / map / cast?
-
-### 3c. Type + state at the moment of failure
-- Actual runtime type (use a debugger or log)
-- Expected type
-- Why do they differ?
-
-### 3d. Vendor / framework internals
-- Open the vendor source at the EXACT line from the stack trace
-- Trace backwards: who calls this method, with what args?
-- What condition routes execution into the failing branch?
-
-### Debugging tools
-
-Use the right tool, not just `console.log`:
-
-| Tool | When |
-|------|------|
-| **Debugger breakpoint** | Step through suspect code, inspect locals |
-| **Conditional breakpoint** | Stop only when `x == nil` / `id == 42` |
-| **Logpoint** (debugger) | Inject log without modifying source — useful in prod-like envs |
-| **Memory / heap profiler** | Suspected memory leak or unbounded growth |
-| **CPU profiler** | Slow path / hot loop |
-| **Network trace** (Wireshark, browser devtools) | Wire-level issue with external API |
-| **strace / dtruss** | Syscall-level (file, network) on Unix |
-| **Time-travel debugger** (rr, Replay) | Hard non-determinism, race conditions |
-| **Distributed tracing** (OpenTelemetry, Jaeger) | Cross-service latency or error origin |
-
-### Gate
-- [ ] Full call chain documented
-- [ ] Source of faulty data identified
-- [ ] Actual vs expected type / state recorded
-
----
-
-## Step 4: ROOT CAUSE — answer 3 questions
-
-1. **Why does it fail?** — the specific technical cause
-2. **Why didn't it fail before?** — what changed (deploy, dep, data shape, config, traffic)
-3. **Reproduction conditions?** — exact inputs / state that trigger it
-
-If you cannot answer all 3 → return to Step 3.
-
-### Gate
-- [ ] All 3 questions answered with **evidence**, not speculation
-
----
-
-## Step 5: HIDDEN STATE — check 6 sources
-
-"Sometimes works, sometimes doesn't" bugs live here.
-
-### 5a. Cache / serialization
-- Cached object lost transient fields / lazy-loaded properties?
-- Stale cache has OLD shape; new code expects NEW shape?
-- Serialize / deserialize changes types? (int↔float, null handling, enum↔string, date timezone)
-
-### 5b. Database / storage
-- Collation / encoding affecting comparisons (e.g., case-insensitive collation hiding duplicates)?
-- DB default values mismatch with code expectations (null vs empty string)?
-- Schema on prod vs schema in code (migration not applied)?
-- **Read replica lag** — write to primary, read from replica returns stale data?
-
-### 5c. Concurrency / async
-- **Race condition** — two requests modifying shared state simultaneously
-- **Deadlock / livelock** — lock acquired but never released
-- **Goroutine / async leak** — handler returned but background work continues
-- **Request context cancelled** while async work depended on it
-- **Channel / queue overflow** — messages dropped silently
-- Use logs with nanosecond timestamps + request IDs to reconstruct the timeline
-
-### 5d. Runtime / compiled cache
-- OPcache / bytecode cache serving old file
-- Compiled config / routes / views not cleared after deploy
-- CDN / proxy cache serving stale asset
-- Browser cache / service worker
-
-### 5e. Environment
-- Env vars on prod correct + complete?
-- Runtime version (Node 20 vs 18, Go 1.22 vs 1.21) differs from local?
-- Dependency versions differ (lockfile drift, transitive update)?
-
-### 5f. Multi-tenancy (SaaS-specific)
-- **Tenant ID leak** — query missing `WHERE tenant_id = ?`
-- Cache key missing tenant prefix → tenant A sees tenant B's data
-- Background job inherits wrong tenant context
-- Connection pool reused across tenants without reset
-
-### Gate
-- [ ] All 6 categories considered (write N/A if not applicable)
-- [ ] At least one category identified as the hidden state source (or explicitly ruled out)
-
----
-
-## Step 6: FIX
-
-Only after Step 4 is answered. The fix MUST:
-
-- Address **root cause**, not symptom
-- Be defensive at **trust boundaries** (cache, DB, external API, user input) — NOT in internal logic
-- Handle the specific edge case found, without breaking the normal path
-- Be small + reviewable
-- Land in the correct layer (per `~/.claude/architecture/ddd-architecture.md`)
-
-### Boundary defense pattern
-For data-shape bugs from external sources: validate / coerce at the adapter, not inside business logic.
-
-### Gate
-- [ ] Fix targets root cause
-- [ ] Defended at the boundary
-- [ ] Normal code path not regressed
-
----
-
-## Step 7: VERIFY
-
-- Reproduce the Step 4 conditions → confirm fix works
-- Normal code path still works
-- Cache-related → test fresh load AND cached load
-- Concurrency-related → reproduce under **load test** (10-100x normal concurrency)
-- Verify against the deployed version (repeat Step 2)
-- Add a **regression test** in the appropriate layer
-
-### Gate
-- [ ] Original failure no longer reproducible
-- [ ] Normal flow works
-- [ ] Cached / serialized paths both work (if applicable)
-- [ ] Load-tested if concurrency-related
-- [ ] Regression test added
-
----
-
-## Final Report
-
-```markdown
-## Bug: {short description}
-
-### Root Cause
-{Specific technical cause from Step 4 Q1}
-
-### Why it didn't fail before
-{What changed: deploy / dependency / data shape / config / traffic / runtime}
-
-### Reproduction
-{Exact steps + data + environment}
-
-### Hidden state source
-{Cache / DB / Concurrency / Runtime / Env / Multi-tenant — or "none"}
-
-### Fix
-- File: `path/to/file:line`
-- Layer: {handler / usecase / infra adapter}
-- Approach: {boundary defense / type coercion / locking / cache invalidation / etc.}
-- Why this is root-cause, not symptom: {explanation}
-
-### Regression test
-- File: `path/to/test:line`
-- Reproduces the original failure when fix removed
-
-### Verification
-- [x] Original failure no longer reproducible
-- [x] Normal path works
-- [x] Cached path works (if applicable)
-- [x] Load tested (if concurrency-related)
-```
-
----
-
-## Hard Rules
-
-- **DO NOT GUESS** — trace evidence, never infer from variable names
-- **DO NOT FIX BEFORE UNDERSTANDING** — premature fix = new bug
-- **VERIFY DEPLOYED CODE** — never assume prod = local
-- **CHECK CACHE FIRST** for intermittent bugs
-- **CHECK MULTI-TENANCY** if SaaS-style
-- **ONE ROOT CAUSE per bug** — if multiple possibilities remain, trace further
-- **TIME-BOX investigation** — if >2 h without convergence, ask for help
-- **REGRESSION TEST required** — fix without test = bug returns
-
----
-
-## Related Skills
-
-| When | Use |
-|------|-----|
-| Bug is understood, just needs a fix | `/fix-hotfix` |
-| Production is down | `/fix-incident` (then this skill after mitigation) |
-| Write regression test after fix | `/review-tdd` |
-| Research how others solved similar bugs | `/research-web` |
-
-## Recommended Agents
-
-| Phase | Agent | Purpose |
-|-------|-------|---------|
-| Trace | `@code-reviewer` | Independent reading of call chain |
-| Hidden state — DB | `@db-designer` | Schema, indexes, collation, replication |
-| Hidden state — concurrency | `@perf-optimizer` | Race, deadlock, async leak |
-| Hidden state — security/tenancy | `@security-audit` | Tenant isolation, auth context |
-| Fix | Stack-specific dev agent | Boundary-defensive fix |
-| Verify | `@test-writer` | Regression test |

package/assets/skills/marketing/logo/SKILL.md

@@ -1,252 +0,0 @@
----
-name: marketing-logo
-description: Generate comprehensive logo design specifications, brand identity guidelines, and visual concepts. Use when user says "design logo", "create logo", "brand identity", "logo concept", "visual identity".
----
-
-# Logo Design Skill
-
-Produce a logo + brand identity **specification** that a designer can execute (or you can use as a direct prompt to a generative tool). Output is a brand guidelines doc, not finished art.
-
-## When to use this skill
-
-- ✅ Brand new identity (no existing logo)
-- ✅ Rebrand / refresh of an existing logo + guidelines
-- ✅ Need a deliverable spec for a designer to execute
-- ❌ Just need a quick icon variation → use a design tool directly
-- ❌ Full marketing plan (logo + content + video) → use `/marketing`
-- ❌ Video-specific visuals → use `/marketing-video`
-
----
-
-## Workflow
-
-```
-DISCOVER → CONCEPT → DESIGN → REFINE → DELIVER
-```
-
----
-
-## Phase 1: DISCOVER (30 min)
-
-**Goal:** capture brand intent before sketching.
-
-### Discovery brief
-
-Ask the user (skip what's known):
-
-| Field | Example |
-|-------|---------|
-| Name + tagline | "Acme — DevOps for indie teams" |
-| 3-5 personality adjectives | "modern, technical, irreverent, sharp, friendly" |
-| Primary audience | "Solo / small-team backend engineers" |
-| Industry | "Developer tools / SaaS" |
-| Competitors (3-5) | + 1 line each on what their logo says about them |
-| Style direction (pick 1-2) | minimal / wordmark / monogram / abstract mark / illustrative / mascot |
-| What to AVOID | "no cliché cloud icons, no gradients on the mark" |
-| Where it lives | favicon + GitHub avatar + landing hero + dark / light themes + print |
-| Color hints | "must work in single-color print + on dark UI" |
-| Budget for the brand | "MVP — logo + 1 palette + 2 fonts" vs "full system" |
-
-### Gate
-- [ ] Personality adjectives captured (forces concept differentiation)
-- [ ] Competitor scan done (don't accidentally copy)
-- [ ] Style direction narrowed to 1-2
-- [ ] Avoid-list captured
-
----
-
-## Phase 2: CONCEPT — propose 3 directions
-
-**Goal:** present 3 *distinct* concepts. Same concept in 3 colors ≠ 3 concepts.
-
-Each concept must have:
-
-```markdown
-## Concept {N}: {short name}
-
-**Direction:** {wordmark / monogram / abstract mark / etc.}
-**Rationale:** Why this matches the brand personality + audience. Cite 2-3 adjectives.
-**Differentiation:** What competitor it does NOT look like, and why that matters.
-**ASCII sketch** (rough — describes shape, not pixel-perfect):
-```
-   ___________
-  | A C M E   |
-  |___________|
-```
-**Inspiration:** 2-3 reference links (existing logos, styles)
-**Risks:** What could go wrong (e.g., "monogram unreadable below 24px")
-```
-
-### Concept variety rules
-- Different *form* (wordmark vs mark vs combination)
-- Different *feel* (geometric vs hand-drawn vs typographic)
-- Different *complexity* (minimal vs detailed)
-
-### Gate
-- [ ] 3 concepts presented
-- [ ] Each has rationale + differentiation + risk
-- [ ] **User selected ONE** (or asked for hybrid — repeat phase)
-
----
-
-## Phase 3: DESIGN — flesh out the chosen concept
-
-**Goal:** produce specifications a designer can build.
-
-### 3.1 Logo construction
-
-```markdown
-### Logo: {name}
-
-**Lockup**
-- Primary: {wordmark / mark / mark + wordmark side-by-side / stacked}
-- Secondary (when primary doesn't fit): {variant}
-- Icon-only (favicon, avatar): {variant}
-
-**Geometry**
-- Grid: {e.g., "8-unit grid, mark fits in 8x8 square"}
-- Proportions: {e.g., "wordmark cap-height = 5 units; mark = 8 units; gap = 2 units"}
-
-**Clear space**
-- Minimum: {e.g., "1 cap-height on all sides"}
-
-**Minimum size**
-- Digital: {e.g., "24px height"}
-- Print: {e.g., "8mm height"}
-```
-
-### 3.2 Color palette
-
-Pick a primary + secondary + neutrals. Provide every color in:
-- HEX, RGB, HSL
-- CMYK (for print)
-- WCAG AA contrast against white and against black (note pass / fail)
-- Tailwind variable name (if relevant)
-
-```markdown
-| Token | HEX | RGB | HSL | Use |
-|-------|-----|-----|-----|-----|
-| `--brand-primary`   | #0F172A | 15,23,42  | 222 47% 11% | logo, headlines |
-| `--brand-accent`    | #14B8A6 | 20,184,166 | 173 80% 40% | CTA, links |
-| `--neutral-fg`      | #1F2937 | 31,41,55  | 220 26% 14% | body text |
-| `--neutral-bg`      | #F8FAFC | 248,250,252 | 210 40% 98% | page bg |
-```
-
-### 3.3 Typography
-
-Pick 1 display + 1 body font (or 1 font in 2 weights). Note:
-- Family + fallback stack
-- Weights used (display, body, light)
-- Pairing rationale (1 line)
-- License (open / Google Fonts / commercial)
-
-### 3.4 Voice
-- 3 voice attributes (e.g., "direct, witty, never corporate-speak")
-- 3 do / 3 don't examples (1 line each)
-
-### Gate
-- [ ] All lockup variants specified
-- [ ] Palette has WCAG contrast notes
-- [ ] Typography choice has rationale + license
-- [ ] Voice has do/don't examples
-
----
-
-## Phase 4: REFINE
-
-**Goal:** test the design against real use, iterate.
-
-### Test scenarios (write down result for each)
-- [ ] Favicon at 16×16 — still recognizable?
-- [ ] On dark background — does it still work?
-- [ ] Single-color print (black-only fax test) — still readable?
-- [ ] Next to 2-3 competitor logos — does it stand out?
-- [ ] At 100% scale on hero — does it carry the page?
-
-### Feedback loop
-- Present to user with each scenario
-- Capture changes requested
-- If >2 rounds of changes → consider re-concepting (Phase 2)
-
-### Gate
-- [ ] All 5 scenarios tested
-- [ ] User approved final version
-
----
-
-## Phase 5: DELIVER — brand guidelines doc
-
-**Goal:** ship a single doc + asset list a designer / dev can use.
-
-### `brand-guidelines.md` skeleton
-
-```markdown
-# {Brand} Brand Guidelines
-
-## Logo
-- {Primary, secondary, icon lockups as files: SVG + PNG}
-- Clear space + min size rules
-- Wrong uses (with examples: don't recolor, don't squish, don't add effects)
-
-## Color
-- Token table from Phase 3.2
-- Usage rules (when primary vs accent)
-- Accessibility (contrast notes)
-
-## Typography
-- Stack from Phase 3.3
-- Hierarchy: H1/H2/H3/body sizes
-- Web vs print
-
-## Voice
-- From Phase 3.4
-- Sample headline + body + CTA copy
-
-## Examples
-- 1 hero, 1 card, 1 button shown with the brand applied
-```
-
-### Asset checklist (what to hand to designer / dev)
-
-- [ ] `logo-primary.svg` + `logo-primary.png` (1x, 2x, 4x)
-- [ ] `logo-secondary.svg` + `.png`
-- [ ] `logo-mark.svg` + `.png`
-- [ ] `favicon.ico` (16, 32, 48), `apple-touch-icon.png` (180×180), `og-image.png` (1200×630)
-- [ ] Social avatars: square 400×400 + cover per platform (Twitter 1500×500, LinkedIn 1128×191, etc.)
-- [ ] Color tokens: `colors.css` (CSS variables) + `tailwind.config.js` snippet (if Tailwind)
-- [ ] Brand guidelines PDF or `.md`
-
-### Gate
-- [ ] Guidelines doc written
-- [ ] Asset checklist exists (even if generation is by a designer)
-- [ ] Developer-ready tokens included (CSS / Tailwind)
-
----
-
-## Hard Rules
-
-- **3 *distinct* concepts in Phase 2** — same concept in 3 colors = lazy
-- **WCAG AA contrast minimum** on text colors
-- **Mark must read at 16px** — if it doesn't, redesign, don't compromise
-- **No gradient on the primary mark** — gradients don't print, don't fax, don't embroider well
-- **License-clean fonts only** — no "found on the internet" type
-
----
-
-## Related Skills
-
-| When | Use |
-|------|-----|
-| Full marketing plan (logo + content + video) | `/marketing` |
-| Write content with the brand | `/marketing-content` |
-| Create video with the brand | `/marketing-video` |
-| Document brand guidelines as a doc | `/docs-write` |
-
-## Recommended Agents
-
-| Phase | Agent | Purpose |
-|-------|-------|---------|
-| DISCOVER | `@docs-writer` | Capture brand brief |
-| CONCEPT | `@clean-architect` | Structure the system |
-| DESIGN | `@docs-writer` | Spec documents |
-| DELIVER | `@docs-writer` | Brand guidelines doc |