moicle 2.0.0 → 2.1.0

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

@@ -33,16 +33,32 @@ Before responding:
 2. Stack-specific doc for the affected service
 3. Runbook for the affected component (`docs/runbooks/` or wiki)
 
----
+## Severity
+
+Use `~/.claude/architecture/_shared/severity-levels.md` (incident severity table — P1-P4 with response times).
+
+### Ambiguous severity (P2 vs P3)?
+Decide UP if any apply:
+- Revenue impact (checkout, payment, signups blocked)
+- Security risk (auth, data exposure)
+- Data integrity at risk (writes might be lost / corrupted)
+- Regulatory / SLA breach
+- Pattern matches a prior P2+ (e.g., same DB instance flaky again)
+
+Otherwise: P3.
 
-## Severity Levels
+### Escalation criteria
 
-| Level | Description | Response Time | Examples |
-|-------|-------------|---------------|----------|
-| **P1** | Critical — complete outage / data loss / security breach | <15 min | Site down, DB corrupted, secret leak |
-| **P2** | High — major degradation, 50%+ users affected | <1 h | Login broken, payment failing |
-| **P3** | Medium — partial degradation, <50% users | <4 h | One feature broken |
-| **P4** | Low — minor issue, no significant impact | <24 h | UI glitch |
+Page or escalate when:
+
+| Trigger | Action |
+|---------|--------|
+| P1 on customer-facing system | Page CTO / engineering lead within 15 min |
+| P1 + data loss / breach | Page legal + security lead immediately |
+| P2 lasting >2 hours without mitigation | Page engineering lead, consider promoting to P1 |
+| P1/P2 spanning >1 shift | Schedule formal handoff (see Phase 1.5) |
+| Customer-facing comms required | Notify support + comms lead within 30 min |
+| Public disclosure may be needed (security) | Notify legal + comms + leadership |
 
 ---
 
@@ -52,14 +68,15 @@ Before responding:
 
 ### Actions
 1. Capture: what, when, who's affected, error messages, recent deploys
-2. Assign severity (P1–P4)
+2. Assign severity (P1–P4) — use ambiguous-severity rule above
 3. Open incident channel (`#incident-{date}-{short-name}`)
 4. Assign roles:
    - **Incident Commander (IC)** — coordinates, makes decisions
    - **Tech Lead** — investigates / fixes
    - **Comms Lead** — updates stakeholders
 5. Page on-call for affected service
-6. Send first status update (template below)
+6. Check escalation criteria above — page additional people if any trigger
+7. Send first status update (template below)
 
 ### First update template
 ```
@@ -71,13 +88,60 @@ Next update: {time}
 ```
 
 ### Gate
-- [ ] Severity assigned
+- [ ] Severity assigned (and escalation triggered if applicable)
 - [ ] IC + Tech Lead identified
 - [ ] Incident channel open
 - [ ] First status sent
 
 ---
 
+## Phase 1.5: HANDOFF (only if shift change during incident)
+
+For incidents spanning >1 shift, do a formal handoff. Skip if same team handles end-to-end.
+
+### Handoff template
+```markdown
+## Incident Handoff: {service} {date}
+
+**From:** {outgoing IC} → **To:** {incoming IC}
+**Channel:** #incident-{slug}
+**Severity:** {current}
+
+### Current state
+- Impact: {what users see right now}
+- Mitigations applied: {list with timestamps}
+- What worked: {list}
+- What didn't: {list}
+
+### Active investigations
+- {open question + who was looking into it}
+
+### Active hypotheses
+- {hypothesis + evidence for/against}
+
+### Open decisions
+- {decision needed + options + recommended choice}
+
+### Next steps
+- {action + owner + ETA}
+
+### People paged / informed
+- {list with role + when paged}
+
+### Pending comms
+- {next update due at HH:MM}
+- {customer-facing status due}
+```
+
+Live walkthrough (5-10 min): outgoing IC walks incoming IC through the timeline + open questions in the incident channel. Both confirm understanding before handoff completes.
+
+### Gate
+- [ ] Handoff doc posted in incident channel
+- [ ] Incoming IC acknowledges + confirms understanding
+- [ ] Stakeholders notified of new IC
+
+---
+
 ## Phase 2: INVESTIGATE (parallel with comms)
 
 **Goal:** find what's broken — don't fix yet, identify it.
@@ -216,23 +280,47 @@ Next update: {time}
 
 ---
 
-## Communication Templates
+## Communication
+
+### Update frequency by severity
 
-**Status update (every {N} min during incident)**
+| Severity | Update cadence | Channels |
+|----------|---------------|----------|
+| P1 | Every 15 min while investigating; every 30 min after mitigation | Incident channel + status page + customer email if >30 min outage |
+| P2 | Every 30 min while investigating; hourly after mitigation | Incident channel + status page |
+| P3 | Hourly | Incident channel |
+| P4 | At start, on mitigation, on resolution | Incident channel |
+
+If nothing new to report, post anyway: "No update — still investigating, next update at HH:MM." Silence creates panic.
+
+### Templates
+
+**Status update**
+```
+[UPDATE {time} UTC] {severity} {service}
+Impact: {what users see — specific, not "issues"}
+Action: {what we're doing right now}
+ETA mitigation: {time or "unknown"}
+Next update: {time}
+```
+
+**Mitigation applied**
 ```
-[UPDATE {time}] {service} — {status}
-Impact: {what users see}
-Action: {what we're doing}
+[MITIGATED {time} UTC] {severity} {service}
+Impact: {reduced from X to Y}
+Mitigation: {what we did}
+Permanent fix: {ETA}
 Next update: {time}
 ```
 
 **Resolved**
 ```
-[RESOLVED {time}] {service}
+[RESOLVED {time} UTC] {service}
+Total duration: {detected → resolved}
 Root cause: {one line}
 Mitigation: {what we did}
-Permanent fix: {ETA or done}
-Postmortem: {date}
+Permanent fix: {deployed at HH:MM | scheduled by DATE}
+Postmortem: {date} — link to come
 ```
 
 ---

package/assets/skills/fix/pr-comment/SKILL.md

@@ -6,290 +6,164 @@ args: PR_NUMBER
 
 # Fix PR Comment Workflow
 
-Workflow for fetching and fixing review comments from a pull request.
+Fetch all review comments on an open PR, address each, push, and respond back to GitHub.
 
-## When to use this skill
+**ARGUMENTS:** `PR_NUMBER` — the PR you authored.
 
-- ✅ Reviewer left comments on an open PR and you need to address each one
-- ✅ You want to track which comments are resolved vs still open
-- ✅ Need to post structured responses back to GitHub
-- ❌ Reviewing PR yourself (you're the reviewer) → use `/review:pr`
-- ❌ No PR yet, just want to clean up branch → use `/review:branch`
-- ❌ Need to fix a brand-new bug found by reviewer → use `/fix:hotfix` first, then this skill
+## When to use this skill
 
-## Usage
+- ✅ Reviewer left comments and you need to address each one
+- ✅ Want to track which comments are resolved vs still open
+- ✅ Need structured responses posted back to GitHub
+- ❌ You are the reviewer → use `/review:pr`
+- ❌ No PR yet → use `/review:branch`
+- ❌ Fix is a brand-new bug surfaced by reviewer → `/fix:hotfix` first, then this skill
 
-```
-/fix:pr-comment {PR_NUMBER}
-```
+---
 
-## Workflow Overview
+## Workflow
 
 ```
-┌──────────────┐   ┌──────────────┐   ┌──────────────┐   ┌──────────────┐
-│ 1. FETCH     │──▶│ 2. ANALYZE   │──▶│ 3. FIX       │──▶│ 4. RESPOND   │
-│   Comments   │   │   Comments   │   │   Issues     │   │   to PR      │
-└──────────────┘   └──────────────┘   └──────────────┘   └──────────────┘
+FETCH → ANALYZE → FIX → RESPOND
 ```
 
 ---
 
 ## Phase 1: FETCH
 
-**Goal**: Fetch all review comments from the PR
-
-### Actions
-
-1. Get PR details:
-   ```bash
-   gh pr view {PR_NUMBER} --json number,title,state,headRefName,baseRefName
-   ```
-
-2. Fetch all review comments:
-   ```bash
-   gh api repos/{owner}/{repo}/pulls/{PR_NUMBER}/comments --jq '.[] | {id: .id, path: .path, line: .line, body: .body, user: .user.login, created_at: .created_at}'
-   ```
-
-3. Fetch PR review threads (for threaded discussions):
-   ```bash
-   gh api repos/{owner}/{repo}/pulls/{PR_NUMBER}/reviews --jq '.[] | {id: .id, user: .user.login, state: .state, body: .body}'
-   ```
-
-4. Get the current diff:
-   ```bash
-   gh pr diff {PR_NUMBER}
-   ```
-
-### Output
-```markdown
-## PR #{NUMBER}: {TITLE}
-
-### Branch
-- Head: {headRefName}
-- Base: {baseRefName}
-
-### Review Comments
-1. **[{file}:{line}]** by @{user}
-   > {comment body}
-
-2. **[{file}:{line}]** by @{user}
-   > {comment body}
+```bash
+PR={number}
+gh pr view $PR --json number,title,state,headRefName,baseRefName,author
+gh pr diff $PR
+gh api repos/{owner}/{repo}/pulls/$PR/comments \
+  --jq '.[] | {id, path, line, body, user: .user.login, created_at}'
+gh api repos/{owner}/{repo}/pulls/$PR/reviews \
+  --jq '.[] | {id, user: .user.login, state, body}'
 ```
 
+Collect into a list. Each comment has: `id`, `file:line`, `author`, `body`, `created_at`.
+
 ### Gate
-- [ ] PR details fetched
-- [ ] Review comments fetched
-- [ ] Current branch checked out
+- [ ] All comments fetched (line-level + review-level)
+- [ ] Current diff loaded
+- [ ] PR is open (closed/merged PR → ask if user really wants to revisit)
 
 ---
 
 ## Phase 2: ANALYZE
 
-**Goal**: Categorize and prioritize comments
-
-### Comment Categories
-
-| Category | Description | Priority |
-|----------|-------------|----------|
-| 🔴 **Bug** | Code bug or logic error | Must fix |
-| 🟠 **Security** | Security concern | Must fix |
-| 🟡 **Architecture** | Design/structure issue | Should fix |
-| 🟢 **Style** | Code style/formatting | Nice to fix |
-| 💬 **Question** | Needs clarification | Respond |
-| 💡 **Suggestion** | Optional improvement | Consider |
-
-### Analysis Output
-```markdown
-## Comment Analysis
+For each comment, classify:
 
-### Must Fix (Critical)
-1. [{file}:{line}] - {summary}
-2. [{file}:{line}] - {summary}
+| Category | Action |
+|----------|--------|
+| **Must-fix** (bug, security, broken test, arch violation) | Fix in this round |
+| **Should-fix** (style, naming, missing test for new code) | Fix unless explicit reason not to |
+| **Discussion** (asking a question, proposing alternative) | Reply with reasoning before fixing |
+| **Nit / preference** (subjective) | Acknowledge + decide; OK to push back politely |
+| **Outdated** (code already changed) | Reply "resolved by {commit}" and resolve thread |
 
-### Should Fix
-1. [{file}:{line}] - {summary}
+Ambiguous comment (e.g., "this feels off")? Ask the reviewer for specifics before guessing.
 
-### Nice to Fix
-1. [{file}:{line}] - {summary}
+Build a triage table:
 
-### Questions to Answer
-1. [{file}:{line}] - {question}
+```markdown
+| # | File:line | Author | Category | Plan |
+|---|-----------|--------|----------|------|
+| 1 | handler.go:42 | @alice | must-fix | extract validation to DTO |
+| 2 | store.go:88 | @bob | discussion | reply: prefer current approach because ... |
 ```
 
 ### Gate
-- [ ] All comments categorized
-- [ ] Priorities assigned
-- [ ] Fix order determined
+- [ ] Every comment classified
+- [ ] Plan written per comment
+- [ ] Ambiguous comments → questions queued for reviewer
 
 ---
 
 ## Phase 3: FIX
 
-**Goal**: Address each comment systematically
-
-### Fix Process
-
-For each comment (in priority order):
+### Rules
+- Fix in order: must-fix → should-fix → discussion outcomes
+- One concern per commit (`fix(handler): validate input in DTO per #pr-comment-1`)
+- After each batch: run build + lint + tests locally
+- Re-run `/review:branch` before pushing
 
-1. **Read the file** at the specified location
-2. **Understand the feedback**
-3. **Apply the fix** following project conventions
-4. **Mark as addressed** in your tracking
-
-### Fix Template
-```markdown
-### Fixing: [{file}:{line}]
-**Comment**: {original comment}
-**Action**: {what you're changing}
-**Status**: ✅ Fixed / ❓ Need clarification / ⏭️ Skipped (reason)
-```
-
-### Commit Strategy
-
-Option A: Single commit for all fixes
-```bash
-git add .
-git commit -m "fix: address PR review comments
-
-- Fix {issue 1}
-- Fix {issue 2}
-- Address {feedback 3}"
-```
-
-Option B: Separate commits per fix (for complex changes)
-```bash
-git commit -m "fix: {specific fix description}"
-```
+### When the fix changes architecture
+If a comment requests something structural (move logic between layers, add a port), use `/feature:refactor` for that subtree, then come back here to respond.
 
 ### Gate
-- [ ] All "Must Fix" addressed
-- [ ] All "Should Fix" addressed
-- [ ] Code compiles/builds
-- [ ] Tests pass
+- [ ] All must-fix items addressed
+- [ ] Build + lint + tests green
+- [ ] Self-review with `/review:branch` clean
 
 ---
 
 ## Phase 4: RESPOND
 
-**Goal**: Push changes and respond to reviewers
-
-### Actions
-
-1. Push the fixes:
-   ```bash
-   git push
-   ```
-
-2. Reply to each comment on GitHub:
-   ```bash
-   # Reply to a specific comment
-   gh api repos/{owner}/{repo}/pulls/{PR_NUMBER}/comments/{comment_id}/replies \
-     -f body="Fixed in {commit_sha}. {additional context if needed}"
-   ```
-
-3. Request re-review:
-   ```bash
-   gh pr edit {PR_NUMBER} --add-reviewer {reviewer_username}
-   ```
+Push commits, then reply on GitHub.
 
-4. Add summary comment to PR:
-   ```bash
-   gh pr comment {PR_NUMBER} --body "$(cat <<'EOF'
-   ## Review Comments Addressed
-
-   ### Fixed
-   - ✅ [{file}:{line}] - {description}
-   - ✅ [{file}:{line}] - {description}
+```bash
+git push
+# Reply to each thread
+gh api repos/{owner}/{repo}/pulls/$PR/comments/{comment_id}/replies -f body="..."
+# Or single summary review
+gh pr review $PR --comment --body "$(cat reply.md)"
+```
 
-   ### Clarifications
-   - 💬 [{file}:{line}] - {response to question}
+### Reply patterns
 
-   ### Deferred
-   - ⏭️ [{file}:{line}] - {reason for deferring}
+**Fixed**
+> Fixed in {sha}. {one-line of what changed}.
 
-   Ready for re-review!
-   EOF
-   )"
-   ```
+**Pushing back (politely)**
+> Considered this — keeping current approach because {specific reason}. Happy to revisit if you have stronger evidence.
 
-### Response Templates
+**Asking back**
+> Could you clarify what you mean by "this feels off"? Is it about {hypothesis A} or {hypothesis B}?
 
-**For bug fixes:**
-```
-Fixed in {commit}. Good catch! The issue was {brief explanation}.
-```
-
-**For style/suggestions:**
-```
-Updated as suggested. Thanks for the feedback!
-```
+**Resolved by other change**
+> Resolved by {sha} earlier in the chain — line {N} no longer exists.
 
-**For questions:**
-```
-{Answer the question}. Let me know if you need more context.
-```
+### Resolve threads
+After replying, mark threads resolved (GitHub UI or API). Don't leave dangling threads — reviewer can't tell what's done.
 
-**For disagreements (respectful):**
-```
-I considered this, but kept the current approach because {reason}. Happy to discuss further if you still have concerns.
+### Re-request review
+```bash
+gh pr edit $PR --add-reviewer {original_reviewer}
 ```
 
 ### Gate
-- [ ] All fixes pushed
-- [ ] Comments replied to
-- [ ] Re-review requested
-- [ ] Summary posted
+- [ ] Every comment has a reply
+- [ ] Threads resolved where appropriate
+- [ ] Commits pushed
+- [ ] Reviewer re-requested
 
 ---
 
-## Quick Reference
-
-### GitHub CLI Commands
-
-```bash
-# View PR
-gh pr view {NUMBER}
+## Final Report
 
-# Get PR comments
-gh api repos/{owner}/{repo}/pulls/{NUMBER}/comments
-
-# Get PR reviews
-gh api repos/{owner}/{repo}/pulls/{NUMBER}/reviews
-
-# Reply to comment
-gh api repos/{owner}/{repo}/pulls/{NUMBER}/comments/{comment_id}/replies -f body="message"
-
-# Add PR comment
-gh pr comment {NUMBER} --body "message"
-
-# Request reviewer
-gh pr edit {NUMBER} --add-reviewer {username}
+```markdown
+## PR #{N}: comments addressed
 
-# View PR diff
-gh pr diff {NUMBER}
+| # | File:line | Category | Resolution | Commit |
+|---|-----------|----------|------------|--------|
+| 1 | handler.go:42 | must-fix | Extracted validation | abc123 |
+| 2 | store.go:88 | discussion | Replied + kept approach | — |
+| 3 | helper.go:5 | nit | Renamed | def456 |
 
-# Checkout PR branch
-gh pr checkout {NUMBER}
+### Build / Lint / Tests: PASS
+### Re-review requested: @{reviewer}
 ```
 
-### Comment Response Etiquette
-
-1. **Be grateful** - Reviewers spent time helping you
-2. **Be clear** - Explain what you changed and why
-3. **Be timely** - Address comments promptly
-4. **Be thorough** - Don't leave comments unaddressed
-5. **Be open** - Accept feedback gracefully
-
 ---
 
-## Success Criteria
+## Hard Rules
 
-PR comments are properly addressed when:
-1. All critical/must-fix comments resolved
-2. All comments have responses
-3. Changes pushed to the PR branch
-4. Reviewers notified for re-review
-5. No new issues introduced
+- **Reply to every comment** — silence reads as ignoring
+- **Push back politely** when you have a real reason; never just close threads
+- **One concern per commit** — easier for reviewer to verify
+- **Run `/review:branch` before pushing** — catch easy issues before reviewer round 2
+- **Don't argue style** when the team has a linter — let the tool decide
 
 ---
 
@@ -299,8 +173,8 @@ PR comments are properly addressed when:
 |------|-----|
 | You are the reviewer | `/review:pr` |
 | Self-review before pushing again | `/review:branch` |
-| Fixing a bug surfaced by review | `/fix:hotfix` |
-| Comment requests architecture refactor | `refactor` → then this skill |
+| Reviewer asked for architectural refactor | `/feature:refactor` |
+| Reviewer surfaced a bug needing investigation | `/fix:root-cause` |
 
 ## Recommended Agents
 
@@ -309,4 +183,4 @@ PR comments are properly addressed when:
 | ANALYZE | `@code-reviewer` | Triage comments by severity |
 | FIX | Stack-specific dev agent | Apply code changes |
 | FIX | `@security-audit` | If comment flagged security |
-| RESPOND | `@docs-writer` | Polish written responses |
+| RESPOND | `@docs-writer` | Polish written replies |