moicle 1.7.0 → 2.1.0

package/assets/skills/feature/refactor/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: feature-refactor
+description: DDD refactoring workflow with phase-based checks and review loop. Refactor existing code to DDD architecture or improve existing DDD structure. Use when user says "refactor", "clean up", "improve code", "restructure", "migrate to ddd", "refactor ddd".
+args: "[MODULE] [DOMAIN]"
+---
+
+# DDD Refactor Workflow
+
+Restructure existing code into DDD layers, or fix drift in an existing DDD module. **Preserves behavior** — refactor structure, never change logic.
+
+**ARGUMENTS:** `<module> <domain>` — e.g., `marketing notification`, `users identity`, `products catalog`
+
+## When to use this skill
+
+- ✅ Migrating a legacy module into DDD layers
+- ✅ Existing DDD module has drifted (fat controller, anemic entity, mixed concerns)
+- ✅ Splitting one domain into multiple bounded contexts
+- ❌ Building a brand-new feature → use `/feature:new`
+- ❌ Just renaming files / variables → just do it
+- ❌ Fixing a bug → use `/fix:hotfix` or `/fix:root-cause`
+
+## Read Architecture First
+
+Detect stack via `~/.claude/architecture/_shared/stack-detection.md`. Load `ddd-architecture.md` + stack doc.
+
+---
+
+## Workflow
+
+```
+0 FOUNDATION → 1 ANALYZE → 2 DOMAIN → 3 INFRA → 4 APP → 5 TESTS → 6 CLEANUP → REVIEW LOOP
+```
+
+Each phase has a Rule Check. Do not skip any phase.
+
+---
+
+## Phase 0: FOUNDATION
+
+**New project (no `domain/` yet):** create
+- `domain/shared/` — base event types, event collector, dispatcher interface
+- Event bus infrastructure
+- App bootstrap/config struct
+
+**Existing project:** verify
+```bash
+ls {domain_root}/shared/ 2>/dev/null && echo PASS || echo NEED SETUP
+ls {eventbus_path}/ 2>/dev/null && echo PASS || echo NEED SETUP
+```
+
+If FAIL → set up foundation before continuing.
+
+### Gate
+- [ ] Shared domain types exist
+- [ ] Event infrastructure exists (if domain raises events)
+
+---
+
+## Phase 1: ANALYZE
+
+**Goal:** read ALL source files in the old module before touching anything.
+
+### Read
+- All files in the module dir
+- Related models / types / enums
+- Routes / providers / screens for this module
+- Existing tests (CRITICAL — used in Phase 5)
+
+### Output to user
+```markdown
+## Refactor Plan: {module} → {domain}
+
+### Current state
+- Entities/models: {list with fields}
+- Usecases (functions): {list with 1-line logic summary}
+- DTOs: {list}
+- Cross-module calls: {list}
+- Side-effects: {notifications / SSE / analytics / async jobs}
+- External deps: {DB, cache, messaging}
+- Endpoints/screens: {list with method + path}
+- Test files: {list with case counts}
+
+### Proposed DDD structure
+- Value objects to extract: {list}
+- Entities: {list}
+- Events: {list}
+- Ports: {list}
+- Usecases: {list}
+- Listeners: {list}
+```
+
+### Gate
+- [ ] All module files read
+- [ ] Plan presented to user
+- [ ] **User CONFIRMED** before continuing
+
+---
+
+## Phase 2: DOMAIN LAYER
+
+Create `domain/{domain}/` (or add to existing).
+
+### Order: VO → entities → events → ports → usecases
+
+- **Value Objects** (`valueobjects/`) — extract typed values (status strings, rates, amounts). Immutable + behavior methods. Stdlib imports only.
+- **Entities** (`entities/`) — convert old models. Constructor + behavior methods + event collection. Add mappers to/from persistence. No framework imports.
+- **Events** (`events/`) — one file per event. Extract from existing direct side-effect calls.
+- **Ports** (`ports/`) — one file per interface. Store ports (persistence), adapter ports (external services). Platform-agnostic naming (`URLParser` not `ShopeeURLParser`). No infra imports.
+- **UseCases** (`usecases/`) — extract business logic from old controllers/handlers/services. Import from `ports/`. Split by concern, ≤200 lines/file. No infra imports.
+
+### Gate
+```bash
+{build_domain} && echo PASS || echo FAIL
+{grep_forbidden in domain/} && echo FAIL || echo PASS
+{cross_domain_check} && echo FAIL || echo PASS
+```
+
+---
+
+## Phase 3: INFRASTRUCTURE LAYER
+
+- Implement port interfaces from `domain/{domain}/ports/`
+- Mapper functions: domain entity ↔ persistence model
+- Compile-time interface check (where supported)
+- NO business logic
+- Keep existing persistence models in place
+
+### Gate
+- [ ] Infra build passes
+- [ ] All port interfaces implemented
+
+---
+
+## Phase 4: APPLICATION LAYER
+
+### 4.1 Listeners (extract side-effects)
+**CRITICAL:** Side-effects (notifications, SSE, analytics, jobs) **MUST NOT** be called directly in usecases or infra. Flow must be: entity collects event → usecase dispatches → listener handles.
+
+- One file per event listener
+- Register in event bus
+
+### 4.2 Service
+- Thin wrapper, delegates to usecases. No business logic.
+
+### 4.3 Handler / Controller / Screen
+- Registration / wiring function
+- Thin: parse → service → return
+- DTOs in separate file
+- **All endpoints must match the old paths + methods**
+
+### Gate
+- [ ] App build passes
+- [ ] Every old endpoint has a new handler at the same path
+
+---
+
+## Phase 5: TESTS
+
+**CRITICAL:** read old tests first, copy every scenario. Do not lose coverage.
+
+1. Read all old test files
+2. List all test cases + business scenarios
+3. Write domain tests covering all of them
+
+### What to test
+- **Entities** — behavior methods, edge cases, business rules (pure, no mocks)
+- **UseCases** — happy + error paths, validation, event collection (mock ports)
+- **Value Objects** — transitions, calculations, edge cases (pure)
+
+### Gate
+- [ ] Old test count ≤ new test count
+- [ ] Every old scenario covered
+- [ ] `{test_command}` passes
+
+---
+
+## Phase 6: INTEGRATION & CLEANUP
+
+### 6.1 Wire up the new module
+- Add registration calls in router / provider / registry
+- Remove old module registrations
+- Endpoints/screens match old paths
+
+### 6.2 Remove old module
+- Delete old directory **only after** build + tests pass
+- Do NOT delete shared models/types other modules still use
+
+### Gate
+```bash
+{full_build} && echo PASS || echo FAIL
+test -d {old_module_path} && echo "FAIL: still there" || echo PASS
+grep -r "{old_import_path}" --include="*.{ext}" . && echo "FAIL: stale imports" || echo PASS
+```
+
+---
+
+## Review Loop
+
+After Phase 6, call `/review:architect {stack} {domain}`. Loop until score ≥ B.
+
+```
+LOOP:
+  1. /review:architect {stack} {domain}
+  2. IF violations severity ≥ MEDIUM:
+       fix all → full build → all tests → GOTO 1
+  3. IF score ≥ B → BREAK
+```
+
+---
+
+## Final Report
+
+```markdown
+## Refactor Complete: {module} → {domain}
+
+### Changes
+- Files created: {N}
+- Files modified: {N}
+- Files deleted: {N}
+
+### Endpoints preserved
+| Old path | New handler | Status |
+|----------|-------------|--------|
+
+### Domain events introduced
+| Event | Listener(s) |
+|-------|-------------|
+
+### Tests
+- Files: {N}, cases: {M}
+- All old scenarios migrated: YES
+
+### Review score: {A/B}
+- Build / Lint / Domain purity / Old module removed / No stale imports / Tests: all PASS
+```
+
+---
+
+## Hard Rules
+
+- **Preserve behavior** — never change business logic during refactor
+- **MUST read old tests** before writing new ones (no scenario lost)
+- **MUST read old code** carefully — don't invent logic from variable names
+- **All endpoints keep their paths** — refactor is invisible to clients
+- **Don't skip phases** — Rule Checks gate the next phase
+- **Multiple modules → same domain:** first module creates the domain dir, others add to it
+- **One module at a time** — finish one before starting the next
+
+---
+
+## Related Skills
+
+| When | Use |
+|------|-----|
+| Building from scratch (no existing code) | `/feature:new` |
+| Just adding tests to untested code | `/review:tdd` |
+| Reviewing the refactor before merging | `/review:branch` |
+| Final architecture check (called automatically in review loop) | `/review:architect` |
+
+## Recommended Agents
+
+| Phase | Agent | Purpose |
+|-------|-------|---------|
+| ANALYZE | `@refactor` | Identify refactor scope |
+| ANALYZE | `@code-reviewer` | Smell detection |
+| PLAN | `@clean-architect` | Architecture alignment |
+| BUILD | Stack-specific dev agent | Implementation |
+| TESTS | `@test-writer` | Domain tests |
+| REVIEW | `@code-reviewer` | Final quality check |

package/assets/skills/fix/hotfix/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: fix-hotfix
+description: Quick bug fix workflow with rollback plan. Use when fixing bugs, hotfixes, urgent issues, production bugs, or when user says "fix bug", "hotfix", "urgent fix", "production issue".
+---
+
+# Hotfix Workflow
+
+Fast-track bug fix with a rollback plan. Use when the cause is identifiable in under an hour of investigation.
+
+## When to use this skill
+
+- ✅ Bug is reproducible and root cause is clear (or quickly identifiable)
+- ✅ Need a fix shipped fast with a rollback plan
+- ✅ Severity ranges from low (minor UI) to high (feature broken)
+- ❌ Production is down right now → use `/fix:incident` first
+- ❌ Bug has been "fixed" multiple times and keeps returning → use `/fix:root-cause`
+- ❌ Building a new feature → use `/feature:new`
+
+## Read Architecture First
+
+Read `ddd-architecture.md` + stack-specific doc — the fix must land in the right layer (usecase / handler / infra) per architecture rules.
+
+## Severity
+
+Use `~/.claude/architecture/_shared/severity-levels.md` (incident table). Hotfix typically covers P2-P4. P1 → start with `/fix:incident` for triage / comms.
+
+---
+
+## Workflow
+
+```
+IDENTIFY → REPRODUCE → FIX → VERIFY → DEPLOY
+                          ↑                ↓
+                          └── ROLLBACK (if needed)
+```
+
+---
+
+## Phase 1: IDENTIFY (≤15 min)
+
+**Goal:** capture exactly what's broken — no speculation.
+
+### Capture
+- Error message / stack trace (verbatim)
+- Steps to reproduce
+- Expected vs actual behavior
+- Environment (prod / staging / dev)
+- Affected users (all / subset / specific tenant)
+- Recent deploys / config changes (last 24-48h)
+
+### 5 Whys (worked example)
+> Q1: Why does checkout fail? A1: `OrderService.calculate` returns NaN.
+> Q2: Why NaN? A2: `quantity * price` where price is undefined.
+> Q3: Why undefined? A3: New SKUs from supplier feed have null price.
+> Q4: Why null? A4: Feed schema added optional `price` field, defaulted to null.
+> Q5: Why didn't validation catch it? A5: Import worker skips schema validation for "perf".
+
+→ Root cause: skipped validation in import worker. Fix at the import boundary, not in checkout.
+
+### Gate
+- [ ] Error captured verbatim
+- [ ] Reproduction steps known (or "intermittent" noted)
+- [ ] Severity assigned (P2 / P3 / P4)
+- [ ] Root cause identified (use `/fix:root-cause` if 5 Whys doesn't converge)
+
+---
+
+## Phase 2: REPRODUCE (≤30 min)
+
+**Goal:** reproduce locally before changing any code.
+
+### Steps
+1. Check out the deployed commit (NOT main if main has drifted)
+2. Reproduce with the exact data / inputs from Phase 1
+3. If you can't reproduce → it's environment-specific. Check:
+   - Env vars on prod vs local
+   - DB state / data shape
+   - Cache / CDN state
+   - Runtime version differences
+
+### Gate
+- [ ] Reproduced locally on the deployed commit
+- [ ] OR documented why local reproduction is impossible + plan to test on staging
+
+---
+
+## Phase 3: FIX
+
+**Goal:** smallest correct change at the right layer.
+
+### Rules
+- Fix at the **root cause**, not the symptom
+- Land the fix in the right layer (boundary validation → handler/DTO; business rule → usecase; data shape → infra mapper)
+- **Add a regression test first** (RED), then make it pass (GREEN). See `/review:tdd`.
+- Don't refactor on the fix — separate PR
+- If the fix requires schema migration, plan it as 2 deploys (compatible code first, then migration)
+
+### Boundary defense
+For data-shape bugs (null where not expected, type mismatch from external API): defend at the **trust boundary** (handler / adapter), not inside business logic.
+
+### Gate
+- [ ] Regression test added (red → green)
+- [ ] Fix is in the right layer (per architecture)
+- [ ] No unrelated changes in the PR
+- [ ] Existing tests still pass
+
+---
+
+## Phase 4: VERIFY
+
+**Goal:** confirm fix works without breaking other paths.
+
+### Local
+- [ ] Original failure no longer reproducible
+- [ ] All tests pass (`{test command}`)
+- [ ] Linter clean
+- [ ] Build green
+
+### Staging (if available)
+- [ ] Deploy to staging
+- [ ] Reproduce the failure scenario — should pass
+- [ ] Smoke-test adjacent features (anything sharing the code path)
+- [ ] Monitor logs for 5-15 min
+
+### Gate
+- [ ] Local + staging both verified
+- [ ] No regressions in adjacent features
+
+---
+
+## Phase 5: DEPLOY
+
+### Pre-deploy checklist
+- [ ] PR reviewed (`/review:branch` self + `/review:pr` from teammate)
+- [ ] Rollback plan documented (see below)
+- [ ] On-call notified
+- [ ] CHANGELOG entry
+
+### Rollback plan
+Document **before** deploying:
+- Rollback method: `revert PR` / `redeploy commit {sha}` / `feature flag off` / `DB migration down`
+- Estimated rollback time
+- Who has authority to roll back (usually IC or on-call)
+- Signal to roll back (specific metric + threshold)
+
+### Deploy steps
+1. Deploy via normal pipeline (don't skip CI even under pressure)
+2. Watch metrics + logs for the symptom + adjacent code paths
+3. Hold deploy attention for at least 1× normal request cycle (15-30 min)
+
+### Gate
+- [ ] Deployed successfully
+- [ ] Symptom no longer occurring
+- [ ] No new errors in monitoring
+- [ ] Stakeholders notified
+
+---
+
+## Phase 6: ROLLBACK (if Phase 5 verify fails)
+
+### When to roll back
+- Error rate increases post-deploy
+- New error type appears
+- Adjacent feature breaks
+- Performance degrades meaningfully
+
+### How
+1. Announce: "Rolling back {fix} in 60s due to {observation}"
+2. Execute: revert / redeploy previous / flip flag / migration down
+3. Verify rollback: metrics return to baseline
+4. Post-mortem the rollback — what was missed in Phase 3/4?
+
+---
+
+## Final Report
+
+```markdown
+## Hotfix: {short description}
+
+### Root cause
+{From Phase 1, 5 Whys final answer}
+
+### Fix
+- File: `path/to/file:line`
+- Layer: {handler / usecase / infra / etc.}
+- Approach: {boundary defense / logic correction / data migration}
+
+### Tests
+- Regression test: {file:line}
+- All tests passing
+
+### Deploy
+- Deployed: {timestamp}
+- Verified: {timestamp + how}
+- Rollback plan: {revert / redeploy / flag / migration}
+
+### Severity: {P2 / P3 / P4}
+### Status: SHIPPED ✅ (or ROLLED BACK + reason)
+```
+
+---
+
+## Hard Rules
+
+- **Reproduce before fixing** — no fix lands without local repro
+- **Regression test required** — every fix gets a test that would have caught it
+- **Fix at the root, not the symptom** — patching the symptom invites the bug back
+- **No drive-by refactor** — fix PR is focused, refactor goes in a separate PR
+- **Always have a rollback plan** documented before deploy
+- **Don't skip CI** under pressure — bypassing CI is what causes the next incident
+
+---
+
+## Related Skills
+
+| When | Use |
+|------|-----|
+| Production is down right now | `/fix:incident` first, then hotfix |
+| Bug keeps coming back after fixes | `/fix:root-cause` |
+| Need to write regression test first | `/review:tdd` |
+| Bug is on an open PR | `/fix:pr-comment` |
+| Self-review before opening PR | `/review:branch` |
+
+## Recommended Agents
+
+| Phase | Agent | Purpose |
+|-------|-------|---------|
+| IDENTIFY | Stack-specific dev agent | Read error context |
+| FIX | Stack-specific dev agent | Apply the fix |
+| FIX | `@security-audit` | Security-related bugs |
+| VERIFY | `@test-writer` | Regression test |
+| VERIFY | `@code-reviewer` | Quick code review |
+| DEPLOY | `@devops` | CI/CD + monitoring |