codingbuddy-rules 5.2.0 → 5.4.0

package/.ai-rules/skills/incident-response/severity-classification.md

@@ -1,145 +1,19 @@
-# Severity Classification
+# Severity Classification (Incident Operations)
 
-Objective severity classification based on SLO burn rates and business impact.
+> **Canonical source:** P1/P2/P3/P4 severity level **definitions**, impact criteria, and response expectations live in [`packages/rules/.ai-rules/rules/severity-classification.md`](../../rules/severity-classification.md) under *Production Incident Severity*.
+>
+> This file narrows that canonical scale to **operational guidance** for incident response: how to classify in practice, the math behind burn rates, the decision tree, and what to include in an incident report.
 
 ## The Classification Rule
 
 **Classify severity BEFORE taking any action.** Severity determines:
+
 - Response time expectations
 - Who gets notified
 - Resource allocation priority
 - Communication cadence
 
-## Severity Matrix
-
-### P1 - Critical
-
-**SLO Burn Rate:** >14.4x (consuming >2% error budget per hour)
-
-**Impact Criteria (ANY of these):**
-- Complete service outage
-- >50% of users affected
-- Critical business function unavailable
-- Data loss or corruption risk
-- Active security breach
-- Revenue-generating flow completely blocked
-- Compliance/regulatory violation in progress
-
-**Response Expectations:**
-
-| Metric | Target |
-|--------|--------|
-| Acknowledge | Within 5 minutes |
-| First update | Within 15 minutes |
-| War room formed | Within 15 minutes |
-| Executive notification | Within 30 minutes |
-| Customer communication | Within 1 hour |
-| Update cadence | Every 15 minutes |
-
-**Escalation:** Immediate page to on-call, all hands if needed
-
-**Example Incidents:**
-- Production database unreachable
-- Authentication service down
-- Payment processing 100% failure
-- Major cloud region outage affecting services
-- Data breach detected
-
----
-
-### P2 - High
-
-**SLO Burn Rate:** >6x (consuming >5% error budget per 6 hours)
-
-**Impact Criteria (ANY of these):**
-- Major feature unavailable
-- 10-50% of users affected
-- Significant performance degradation (>5x latency)
-- Secondary business function blocked
-- Partial data integrity issues
-- Key integration failing
-
-**Response Expectations:**
-
-| Metric | Target |
-|--------|--------|
-| Acknowledge | Within 15 minutes |
-| First update | Within 30 minutes |
-| Status page update | Within 30 minutes |
-| Stakeholder notification | Within 1 hour |
-| Update cadence | Every 30 minutes |
-
-**Escalation:** Page on-call during business hours, notify team lead
-
-**Example Incidents:**
-- Search functionality completely broken
-- 30% of API requests failing
-- Email notifications not sending
-- Third-party payment provider degraded
-- Mobile app login issues for subset of users
-
----
-
-### P3 - Medium
-
-**SLO Burn Rate:** >3x (consuming >10% error budget per 24 hours)
-
-**Impact Criteria (ANY of these):**
-- Minor feature impacted
-- <10% of users affected
-- Workaround available
-- Non-critical function degraded
-- Cosmetic issues affecting usability
-- Performance slightly degraded
-
-**Response Expectations:**
-
-| Metric | Target |
-|--------|--------|
-| Acknowledge | Within 1 hour |
-| First update | Within 2 hours |
-| Resolution target | Within 8 business hours |
-| Update cadence | At milestones |
-
-**Escalation:** Create ticket, notify team channel
-
-**Example Incidents:**
-- Report generation slow but working
-- Specific browser experiencing issues
-- Non-critical API endpoint intermittent
-- Email formatting broken
-- Search results slightly inaccurate
-
----
-
-### P4 - Low
-
-**SLO Burn Rate:** >1x (projected budget exhaustion within SLO window)
-
-**Impact Criteria (ALL of these):**
-- Minimal or no user impact
-- Edge case or rare scenario
-- Cosmetic only
-- Performance within acceptable range
-- Workaround trivial
-
-**Response Expectations:**
-
-| Metric | Target |
-|--------|--------|
-| Acknowledge | Within 1 business day |
-| Resolution target | Next sprint/release |
-| Update cadence | On resolution |
-
-**Escalation:** Backlog item, routine prioritization
-
-**Example Incidents:**
-- Minor UI misalignment
-- Rare edge case error
-- Documentation inconsistency
-- Non-user-facing optimization opportunity
-
----
+See the canonical severity matrix for P1-P4 definitions, impact criteria, and response expectations. This file does **not** redefine those levels — refer to the canonical document whenever you need the authoritative criteria.
 
 ## Error Budget Integration
 
@@ -170,10 +44,10 @@ Burn Rate = 1.44 / 0.1 = 14.4x (P1!)
 | Tier 2 (Important) | 99.9% | 0.1% | 43.8 minutes |
 | Tier 3 (Standard) | 99.5% | 0.5% | 3.65 hours |
 
----
-
 ## Classification Decision Tree
 
+Use this when an incident is detected and you need to assign severity quickly.
+
 ```
 Is the service completely unavailable?
 ├── Yes → P1
@@ -208,8 +82,6 @@ Is impact minimal/cosmetic only?
 └── No → Default to P3 (when uncertain)
 ```
 
----
-
 ## When Uncertain, Classify Higher
 
 **Rule:** If you're unsure between two severity levels, classify higher.
@@ -218,21 +90,21 @@ Is impact minimal/cosmetic only?
 - Unsure between P2 and P3? → Classify as P2
 - Unsure between P3 and P4? → Classify as P3
 
-**Rationale:** Over-response is better than under-response. You can always downgrade.
-
----
+**Rationale:** Over-response is better than under-response. You can always downgrade. This rule is also stated in the canonical document; it is repeated here because during an incident you must be able to act without following links.
 
 ## Severity Changes During Incident
 
 Severity can change as you learn more:
 
 **Upgrade when:**
+
 - Impact wider than initially assessed
 - More users affected than thought
 - Business impact greater than estimated
 - Mitigation not working
 
 **Downgrade when:**
+
 - Successful mitigation reduced impact
 - Fewer users affected than thought
 - Workaround discovered
@@ -240,8 +112,6 @@ Severity can change as you learn more:
 
 **Always communicate severity changes** to all stakeholders immediately.
 
----
-
 ## Include in Incident Reports
 
 When documenting severity, always include:
@@ -254,3 +124,9 @@ Impact: [Brief description]
 SLO Status: [Which SLO breaching]
 Error Budget Remaining: [Percentage]
 ```
+
+## Relationship to Code Review Severity
+
+Code review uses a **different** severity scale (`critical`/`high`/`medium`/`low`) for PR approval gating. The two scales are not interchangeable — see [`rules/severity-classification.md`](../../rules/severity-classification.md#mapping-between-scales) for the narrow cases where they correspond (e.g., when a `critical` code review finding that shipped becomes an incident).
+
+Do **not** mix the two scales in incident documents. Use P1-P4 here.

package/.ai-rules/skills/pr-review/SKILL.md

@@ -74,6 +74,8 @@ Security, Correctness, and Test Coverage must ALWAYS be reviewed. No exceptions.
 
 ## Quick Reference
 
+> **Severity source:** The `Critical`/`High`/`Medium`/`Low` levels used below are the **Code Review Severity** scale defined in [`../../rules/severity-classification.md`](../../rules/severity-classification.md#code-review-severity). This skill decides *which dimensions to review at each level*; the canonical file defines *what counts as each level*. Do not conflate these levels with production incident severity (P1-P4).
+
 ### Priority Levels
 
 | Priority | Action | Dimensions |

package/.ai-rules/skills/ship/SKILL.md

@@ -137,6 +137,41 @@ If `custom.ship.globalChecks` is configured, run each global check command after
 <command>   # executed from project root
 ```
 
+### Security check (ALL workspaces)
+
+Security audit must run across ALL workspaces, not just affected ones:
+
+```bash
+# Monorepo — run for ALL workspaces (not just affected):
+<pm> audit
+# Or for npm:
+npm audit --workspaces
+```
+
+**Why:** A vulnerability in an unaffected workspace still ships with the project. Security scanning must be comprehensive.
+
+### CI workflow self-inclusion check
+
+When modifying CI workflow files (e.g., `.github/workflows/*.yml`), verify the workflow's `on.push.paths` or `on.pull_request.paths` filter includes the workflow file itself:
+
+```yaml
+# ✅ Correct — workflow file is included in its own paths filter
+on:
+  push:
+    paths:
+      - 'src/**'
+      - '.github/workflows/ci.yml'  # Self-included
+
+# ❌ Wrong — workflow changes won't trigger the workflow
+on:
+  push:
+    paths:
+      - 'src/**'
+      # Missing: .github/workflows/ci.yml
+```
+
+**Why:** If a workflow file is not in its own paths filter, changes to the workflow itself won't trigger CI, making it impossible to validate workflow changes before merging.
+
 If ANY check fails, stop and report the failure. Do NOT proceed to shipping.
 
 ## Step 6: Check Commit Convention

package/.ai-rules/skills/systematic-debugging/SKILL.md

@@ -22,6 +22,45 @@ NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
 
 If you haven't completed Phase 1, you cannot propose fixes.
 
+## Mandatory 6-Step Debugging Sequence
+
+Before ANY debugging attempt, follow this sequence in order:
+
+1. **Validate/Check command** — If the external tool has a validate/check/lint command, run it FIRST. Always. No exceptions.
+2. **Official documentation** — Verify system behavior by reading official docs. No guessing how a system works.
+3. **Hypothesis formation** — Form a hypothesis with evidence from steps 1-2.
+4. **Fix implementation** — Implement the fix based on your hypothesis.
+5. **Local verification** — Verify the fix locally before shipping.
+6. **Ship** — Only ship after local verification passes.
+
+### Validate First Rule
+
+If an external tool, service, or configuration format has a validate/check/lint command, you MUST run it BEFORE any debugging or fix attempts:
+
+| Tool/Format | Validate Command |
+|-------------|-----------------|
+| GitHub Actions | `actionlint` or validate via `act --list` |
+| Docker | `docker compose config` |
+| Kubernetes | `kubectl apply --dry-run=client` |
+| Terraform | `terraform validate` |
+| JSON | `jq .` or schema-specific validators |
+| YAML | `yamllint` |
+| TypeScript | `tsc --noEmit` |
+| ESLint config | `eslint --print-config` |
+
+**Why:** Validation catches syntax and schema errors instantly. Debugging without validation wastes time on issues the tool itself can detect.
+
+### Verify Mental Model Rule
+
+Before assuming how an external system works, read the official documentation first:
+
+- **Never guess** API behavior, config format, or tool behavior from memory
+- **Always verify** against official docs, especially for version-specific behavior
+- **Check changelogs** when upgrading — behavior may have changed between versions
+- If official docs are unavailable, use `--help`, man pages, or source code as reference
+
+**Why:** Stale mental models from past versions or similar-but-different tools cause debugging to chase phantom issues.
+
 ## When to Use
 
 Use for ANY technical issue:

package/lib/init/scaffold.js

@@ -48,11 +48,15 @@ function scaffold(cwd, options = {}) {
   return { skipped: false, dirs: copiedDirs, targetPath: targetDir };
 }
 
+// Directories to skip during recursive copy (runtime state, not project content)
+const SKIP_DIRS = new Set(['.omc']);
+
 function copyDirRecursive(src, dest) {
   fs.mkdirSync(dest, { recursive: true });
   const entries = fs.readdirSync(src, { withFileTypes: true });
 
   for (const entry of entries) {
+    if (entry.isDirectory() && SKIP_DIRS.has(entry.name)) continue;
     const srcPath = path.join(src, entry.name);
     const destPath = path.join(dest, entry.name);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codingbuddy-rules",
-  "version": "5.2.0",
+  "version": "5.4.0",
   "description": "AI coding rules for consistent practices across AI assistants",
   "main": "index.js",
   "types": "index.d.ts",
@@ -14,6 +14,7 @@
     "index.js",
     "index.d.ts",
     ".ai-rules",
+    "!**/.omc",
     "bin",
     "lib"
   ],