moicle 1.7.0 → 2.1.0

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

@@ -0,0 +1,276 @@
+---
+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/content/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: marketing-content
+description: Create content writing strategy including blog posts, social media, newsletters, and SEO content plans. Use when user says "write content", "content strategy", "blog post", "social media content", "content plan", "seo content", "newsletter".
+---
+
+# Content Writer
+
+Workflow for creating content strategy: audience research, content pillars, SEO blog posts, social media plans, newsletters.
+
+## When to use this skill
+
+- ✅ Building a content strategy from scratch (pillars, calendar, channels)
+- ✅ Writing one specific piece (blog post, newsletter, social thread)
+- ✅ Repurposing one piece into multi-channel content
+- ❌ Writing API / project documentation → use `/docs:write` or `/docs:sync`
+- ❌ Writing release notes / changelog → use git history + manual
+- ❌ Designing a video → use `/marketing:video`
+
+---
+
+## Workflow
+
+```
+RESEARCH → PLAN → WRITE → OPTIMIZE → DISTRIBUTE
+```
+
+---
+
+## Phase 1: RESEARCH
+
+**Goal:** understand audience, competitors, and SEO landscape.
+
+### Gather brief
+Ask the user for (skip what's already known):
+
+| Field | Example |
+|-------|---------|
+| Brand / Product | "Acme — DevOps platform for indie teams" |
+| Voice / Tone | "Casual but technical, no marketing fluff" |
+| Primary audience | "Solo / small-team DevOps engineers" |
+| Pain points | "Too many tools, none integrate well" |
+| Goals (pick ≤2) | SEO traffic, lead gen, brand awareness, education, community, thought leadership |
+| Current channels | Blog / X / LinkedIn / Dev.to / YouTube / Newsletter / Discord |
+| Competitors | 3–5 names + what they do well |
+
+### Audience & SEO research
+- **Search intent** for the topic (informational / navigational / transactional / commercial)
+- **Top 10 SERP** results for 3–5 target keywords — what content ranks?
+- **Gaps** competitors miss (more depth, better examples, fresher data)
+- **Keyword set** — primary + 2–5 long-tails per piece
+
+### Gate
+- [ ] Brief captured (skip fields already covered in conversation)
+- [ ] Target keywords with search intent identified
+- [ ] Competitor gap identified
+
+---
+
+## Phase 2: PLAN
+
+**Goal:** define content pillars + calendar.
+
+### Content pillars
+Pick 3–5 themes that ladder up to the brand's positioning. Each pillar gets a mix of formats.
+
+| Pillar | Why it matters to audience | Formats |
+|--------|---------------------------|---------|
+| {pillar 1} | {pain → outcome} | blog, social, newsletter |
+| {pillar 2} | ... | ... |
+
+### Calendar template
+Plan 4–6 weeks ahead. Use a consistent cadence.
+
+| Week | Blog (long-form) | Social (short-form) | Newsletter |
+|------|------------------|---------------------|------------|
+| W1 | {title} | 3 posts (1 educational, 1 hot take, 1 personal) | {topic} |
+| W2 | ... | ... | ... |
+
+### Content mix rule (per channel)
+- **80/20:** 80% value (educate / entertain), 20% promote
+- **Don't post when you have nothing to say** — skip a slot rather than post filler
+
+### Gate
+- [ ] 3–5 pillars defined with audience rationale
+- [ ] Calendar drafted for ≥4 weeks
+- [ ] Channels matched to audience habits
+
+---
+
+## Phase 3: WRITE
+
+**Goal:** draft the actual content. One format at a time.
+
+### Blog post structure (long-form, SEO)
+
+```
+TITLE (≤60 chars, includes primary keyword)
+META DESCRIPTION (≤155 chars, includes primary keyword + CTA)
+
+H1 (matches title or close variant)
+
+HOOK (2–3 sentences: the problem the reader has)
+
+TL;DR (3 bullets: the answer up front)
+
+H2: Problem context — why this matters now
+H2: The solution — your main argument / approach
+   H3: Step 1 / Aspect 1
+   H3: Step 2
+   H3: Step 3
+H2: Common pitfalls — what NOT to do
+H2: Real example — actual code / screenshot / case
+H2: Next steps — what to do today
+
+CTA (1 line: try the product / subscribe / share)
+```
+
+Target length: 1200–2500 words for SEO; 500–1000 for opinion pieces.
+
+### Social thread (X / LinkedIn)
+
+```
+HOOK (1–2 lines — must work alone in the feed)
+↓
+3–7 posts each ≤280 chars
+- Each post stands alone if shared
+- One idea per post
+- Use line breaks
+↓
+CTA (link to blog / signup)
+```
+
+### Newsletter
+
+```
+SUBJECT (≤50 chars, curiosity > clickbait)
+PREVIEW TEXT (≤90 chars, complements subject)
+
+GREETING (personal, 1–2 lines)
+
+MAIN STORY (1 idea, 200–400 words)
+
+LINKS (3–5 curated, with 1-line why-it-matters)
+
+CTA (one ask only)
+
+SIGNATURE
+```
+
+### Writing rules
+- **One idea per paragraph** (≤4 lines)
+- **Active voice** ("the API returns" not "is returned by the API")
+- **Concrete > abstract** (numbers, code, screenshots, names)
+- **Cut filler:** "in order to" → "to", "due to the fact that" → "because", "very important" → "critical"
+- **Read aloud** before publishing — if you stumble, rewrite
+
+### Gate
+- [ ] Draft matches the format's structure
+- [ ] Primary keyword in title + H1 + first 100 words (blog)
+- [ ] Read aloud — no stumbles
+- [ ] At least 1 concrete example (number, code, screenshot, name)
+
+---
+
+## Phase 4: OPTIMIZE
+
+**Goal:** make the content perform.
+
+### Combined checklist (SEO + quality)
+- [ ] Title ≤60 chars, includes primary keyword
+- [ ] Meta description ≤155 chars
+- [ ] H1 matches search intent
+- [ ] H2/H3 use related keywords naturally
+- [ ] Alt text on all images
+- [ ] Internal links to ≥2 related posts
+- [ ] External links to ≥1 authoritative source per major claim
+- [ ] No keyword stuffing (read naturally)
+- [ ] Mobile-friendly: short paragraphs, clear hierarchy
+- [ ] Reading level appropriate for audience (Hemingway grade ≤10 for general)
+- [ ] No typos (run a checker)
+
+### Gate
+- [ ] All checklist items pass (or explicit waiver)
+
+---
+
+## Phase 5: DISTRIBUTE
+
+**Goal:** get the content in front of the right people.
+
+### Per-channel adaptation
+
+| Channel | Adaptation |
+|---------|------------|
+| Blog | Full piece, optimized for search |
+| X | Thread of 3–7 posts pulling key insights + link to blog |
+| LinkedIn | 1 long-form post (200–500 words), no link in body (link in comments) |
+| Dev.to / Hashnode | Republish blog with canonical link to original |
+| Reddit | Comment in relevant thread first, then share post only if community allows |
+| Newsletter | Featured story or short blurb + link |
+| YouTube Shorts / TikTok | 30–60 sec extract of key insight |
+
+### Tracking
+- UTM tags per channel: `?utm_source=X&utm_medium=social&utm_campaign={pillar}`
+- Track per piece: views, time-on-page, scroll depth, conversions
+- Iterate: double down on what works, kill what doesn't after 3 attempts
+
+### Gate
+- [ ] Adapted for each chosen channel
+- [ ] UTM tags applied
+- [ ] Tracking in place
+
+---
+
+## Final Report
+
+```markdown
+## Content Plan: {brand / campaign}
+
+### Strategy
+- Pillars: {list}
+- Audience: {one line}
+- Goal: {primary}
+
+### Calendar (next 4 weeks)
+{table}
+
+### Pieces Drafted
+| Title | Format | Status | Channel |
+|-------|--------|--------|---------|
+| ... | blog | published | site + X + LinkedIn |
+
+### Metrics to Watch
+- {KPI 1, baseline → target}
+- {KPI 2}
+```
+
+---
+
+## Hard Rules
+
+- **One idea per piece** — if you have two, write two pieces
+- **No filler** — every paragraph earns its place
+- **No keyword stuffing** — write for humans first, search engines second
+- **Skip a slot rather than post filler**
+- **Iterate based on data** — kill what doesn't work after 3 attempts
+
+---
+
+## Related Skills
+
+| When | Use |
+|------|-----|
+| Building brand identity (logo + colors) | `/marketing:logo` |
+| Creating video scripts / storyboards | `/marketing:video` |
+| Building a full marketing plan | `/marketing` (combines all three) |
+| Writing project documentation | `/docs:write` |
+
+---
+
+## Recommended Agents
+
+| Phase | Agent | Purpose |
+|-------|-------|---------|
+| RESEARCH | `@docs-writer` | Document research findings |
+| PLAN | `@clean-architect` | Structure pillars and calendar |
+| WRITE | `@docs-writer` | Draft pieces |
+| OPTIMIZE | `@security-audit` | Check for sensitive content / claims |
+| DISTRIBUTE | `@docs-writer` | Channel adaptations |