mindforge-cc 10.0.2 → 10.7.0

package/.mindforge/skills/human-in-the-loop-design/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: human-in-the-loop-design
+version: 1.0.0
+min_mindforge_version: 10.0.4
+status: stable
+triggers: human in the loop, escalation gate, approval threshold, confidence threshold, explanation quality, trust calibration, user override, hitl pattern, agent handoff, supervision design, human review trigger, autonomous boundary
+compose: guardrails-and-safety
+---
+
+# Skill — Human-in-the-Loop Design (Escalation & Supervision Architecture)
+
+## When this skill activates
+When designing agent autonomy boundaries, building escalation gates, calibrating
+confidence thresholds, or implementing approval workflows. Use for any system where
+an AI agent must decide between acting autonomously and requesting human guidance.
+
+Core principle: **Maximum VALUE, not maximum autonomy** — the goal is not to minimize
+human involvement. The goal is to maximize the value delivered. Sometimes the highest-value
+action is asking the human. The art is knowing WHEN.
+
+## Mandatory actions when this skill is active
+
+### Action Classification (Reversibility x Impact Matrix)
+
+1. **Classify every agent action:**
+   ```
+   | Impact \ Reversibility | Easily Reversible      | Hard to Reverse        | Irreversible           |
+   |------------------------|------------------------|------------------------|------------------------|
+   | Low Impact             | AUTONOMOUS             | AUTONOMOUS             | CONFIRM                |
+   | Medium Impact          | AUTONOMOUS             | CONFIRM                | APPROVE                |
+   | High Impact            | CONFIRM                | APPROVE                | APPROVE + WAIT         |
+
+   Levels:
+   - AUTONOMOUS: Agent acts without asking (log for audit)
+   - CONFIRM: Agent acts but shows what it did (user can undo)
+   - APPROVE: Agent proposes, human approves before execution
+   - APPROVE + WAIT: Agent proposes, human approves, agent waits for explicit "go"
+   ```
+
+2. **Per-action classification examples:**
+   ```
+   AUTONOMOUS (act freely):
+   - Reading files
+   - Running read-only queries
+   - Searching codebases
+   - Generating suggestions (not applying them)
+
+   CONFIRM (act, show, allow undo):
+   - Editing existing files
+   - Creating new files in expected locations
+   - Running tests
+   - Installing dev dependencies
+
+   APPROVE (propose, wait for yes):
+   - Deleting files
+   - Modifying configuration
+   - Running destructive commands
+   - Changing auth/security code
+   - Making API calls with side effects
+
+   APPROVE + WAIT (high ceremony):
+   - Deploying to production
+   - Modifying database schema
+   - Changing payment logic
+   - Force-pushing to shared branches
+   - Deleting user data
+   ```
+
+### Escalation Triggers
+
+3. **When to escalate (confidence-based):**
+   ```
+   Always escalate when:
+   - Confidence < 0.7 on the correct approach
+   - Action is irreversible AND high-impact
+   - Multiple valid approaches exist with no clear winner
+   - Task contradicts prior user guidance
+   - Security-sensitive code is being modified
+   - User's intent is ambiguous
+
+   Escalation format:
+   "I need your input on [X].
+    Context: [what I understand about the situation]
+    Options: [A, B, C with tradeoffs]
+    My recommendation: [preferred option + why]
+    What I'm uncertain about: [specific uncertainty]"
+   ```
+
+   Rules:
+   - ALWAYS explain WHY you're escalating (don't just say "I'm not sure")
+   - ALWAYS provide a recommendation (even when uncertain)
+   - ALWAYS state what additional context would resolve the uncertainty
+   - Never escalate without having done research first (don't be lazy)
+
+### Approval Gate Design
+
+4. **Designing low-friction approval UX:**
+   ```
+   Principles:
+   - Fast: approval should take <5 seconds for clear cases
+   - Informative: show WHAT will happen, not just ask "ok?"
+   - Defaulted: suggest the likely answer (approve/reject)
+   - Skippable: allow bulk-approve for repetitive low-risk items
+   - Auditable: log every approval decision with timestamp and rationale
+
+   Good approval request:
+   "I'd like to add an index on users.email (migration file ready).
+    This will lock the table for ~2 seconds during deploy.
+    [Approve] [Reject] [Show migration SQL first]"
+
+   Bad approval request:
+   "Can I make a database change?"
+   ```
+
+   Rules:
+   - Show the EFFECT of the action, not just the action itself
+   - Provide enough context to decide without further research
+   - Offer a way to see more detail (for cautious reviewers)
+   - Default to the safe option (reject) for high-impact actions
+   - Time-box approvals: if no response in X hours, remind or escalate
+
+### Confidence Calibration
+
+5. **Ensuring confidence scores are meaningful:**
+   ```
+   Calibration goal:
+   When the agent says "I'm 90% confident" → it should be correct 90% of the time
+   When the agent says "I'm 50% confident" → it should be correct 50% of the time
+
+   Measuring calibration:
+   - Collect (confidence, actual_outcome) pairs from eval runs
+   - Plot calibration curve (expected accuracy vs actual accuracy)
+   - Perfect calibration = diagonal line
+   - Overconfident = curve below diagonal (says 90%, is right 70%)
+   - Underconfident = curve above diagonal (says 50%, is right 80%)
+
+   Fixing miscalibration:
+   - Overconfident: lower confidence thresholds (escalate more)
+   - Underconfident: raise thresholds (escalate less, trust yourself)
+   - Recalibrate after major model/prompt changes
+   ```
+
+   Rules:
+   - Calibrate quarterly (or after any major agent change)
+   - If overconfident: the agent is making unescalated mistakes → tighten boundaries
+   - If underconfident: the agent is annoying users with unnecessary escalations → loosen
+   - Track calibration as a first-class metric (alongside accuracy)
+
+### Explanation Quality
+
+6. **How to explain escalations effectively:**
+   ```
+   Explanation structure:
+   1. WHAT: what you're asking about (specific, concrete)
+   2. WHY: why you can't decide autonomously (the uncertainty)
+   3. OPTIONS: what the choices are (with tradeoffs)
+   4. RECOMMENDATION: what you'd do if forced to decide
+   5. CONTEXT_GAP: what information would let you decide next time
+
+   Good explanation:
+   "I found two approaches to implement caching (Redis vs in-memory).
+    Redis is more robust but adds infrastructure cost.
+    In-memory is simpler but won't survive restarts.
+    I'd lean toward Redis for production, but I don't know your infra budget.
+    If you tell me the acceptable monthly cost, I can decide this autonomously next time."
+
+   Bad explanation:
+   "Should I use Redis or in-memory caching?"
+   ```
+
+### Trust Building (Progressive Autonomy)
+
+7. **Earning autonomy over time:**
+   ```
+   Trust levels:
+   Level 1 — New agent (restrictive):
+   - APPROVE for any write operation
+   - CONFIRM for most read operations
+   - Escalation rate: high (~30% of actions)
+
+   Level 2 — Established (standard):
+   - AUTONOMOUS for reads and standard writes
+   - CONFIRM for destructive operations
+   - APPROVE for irreversible high-impact actions
+   - Escalation rate: moderate (~10%)
+
+   Level 3 — Trusted (permissive):
+   - AUTONOMOUS for most operations
+   - CONFIRM for irreversible actions
+   - APPROVE only for production deploys and security changes
+   - Escalation rate: low (~3%)
+
+   Level transitions:
+   - Promote: 20 consecutive successful autonomous actions without user correction
+   - Demote: 1 autonomous action that user explicitly reverses or flags as wrong
+   - Demotion is faster than promotion (trust is earned slowly, lost quickly)
+   ```
+
+### Monitoring Escalation Health
+
+8. **Tracking escalation quality:**
+   ```
+   Metrics to monitor:
+   - Escalation rate: % of actions that require human input
+   - False escalation rate: % of escalations where human says "just do it"
+   - Missed escalation rate: % of autonomous actions that were wrong
+   - Approval latency: time between escalation and human response
+   - Rubber-stamp rate: % of approvals decided in <2 seconds (too fast = not reading)
+
+   Healthy ranges:
+   - Escalation rate: 5-15% (too low = risky, too high = annoying)
+   - False escalation rate: <20% (too high = boundaries too tight)
+   - Missed escalation rate: <2% (too high = boundaries too loose)
+   - Rubber-stamp rate: <30% (too high = approval fatigue, redesign needed)
+   ```
+
+   Rules:
+   - If rubber-stamp rate is high: reduce approval friction or widen autonomy
+   - If missed escalation rate is high: tighten boundaries immediately
+   - Review escalation metrics weekly (don't let them drift)
+   - Treat high rubber-stamp rate as a UX bug (users are being annoyed, not helped)
+
+## Self-check before task completion
+
+Before marking a task done when this skill was active:
+
+- [ ] Are actions classified by reversibility x impact (autonomous/confirm/approve)?
+- [ ] Do escalation triggers include: low confidence, irreversible actions, ambiguity?
+- [ ] Is the approval UX low-friction (fast, informative, defaulted)?
+- [ ] Are explanations structured (what, why, options, recommendation, context gap)?
+- [ ] Is progressive autonomy designed (trust levels with promotion/demotion)?
+- [ ] Are escalation health metrics defined (false escalation rate, rubber-stamp rate)?
+- [ ] Is confidence calibration measured (says 90% → right 90%)?
+- [ ] Does the guardrails-and-safety skill co-activate for safety-critical boundaries?

package/.mindforge/skills/i18n-architecture/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: i18n-architecture
+version: 1.0.0
+min_mindforge_version: 0.3.0
+status: stable
+triggers: i18n architecture, message catalog, pluralization rule, ICU message format, RTL layout, locale detection, translation loading, internationalization setup, language fallback, number formatting, date locale, translation management
+---
+
+# Skill — Internationalization Architecture
+
+## When this skill activates
+Any task involving multi-language support, locale handling, message catalogs,
+RTL layouts, number/date formatting, or translation infrastructure.
+
+## Mandatory actions when this skill is active
+
+### Before implementing i18n
+1. Audit all user-facing strings in the codebase.
+2. Define the locale detection strategy.
+3. Choose a message format that handles plurals and gender.
+
+### Message format (ICU MessageFormat)
+
+**Why ICU:**
+- Handles plurals correctly across languages (some have 6 plural forms).
+- Handles gender agreement.
+- Handles select/choice patterns.
+- Industry standard supported by most i18n libraries.
+
+**Examples:**
+```
+{count, plural,
+  =0 {No items}
+  one {# item}
+  other {# items}
+}
+
+{gender, select,
+  male {He liked your post}
+  female {She liked your post}
+  other {They liked your post}
+}
+```
+
+**Critical rule:** NEVER concatenate strings for messages.
+- BAD: `"Hello " + name + ", you have " + count + " messages"`
+- GOOD: `"Hello {name}, you have {count, plural, one {# message} other {# messages}}"`
+
+### Catalog structure
+
+**One file per locale, namespaced by feature:**
+```
+locales/
+  en/
+    common.json
+    auth.json
+    dashboard.json
+  fr/
+    common.json
+    auth.json
+    dashboard.json
+```
+
+**Rules:**
+- Keys are semantic, not the English text (`auth.loginButton` not `"Log in"`).
+- Flat keys with dot notation or nested objects — pick one, be consistent.
+- Never store HTML in translation strings (use interpolation components).
+- Keep a "base" locale (usually en) as the source of truth.
+
+### Loading strategy
+
+**Lazy-load per route/namespace:**
+- Do NOT load all locales upfront — only the active locale.
+- Do NOT load all namespaces — only what the current route needs.
+- Prefetch the next likely namespace on navigation intent.
+
+**Implementation:**
+```javascript
+// Load only when needed
+const messages = await import(`./locales/${locale}/${namespace}.json`);
+```
+
+**Fallback chain:**
+- Specific locale (fr-CA) → base locale (fr) → default locale (en).
+- Missing key in active locale → fall back, log warning in development.
+
+### Locale detection
+
+**Priority order:**
+1. User explicit preference (stored in profile/cookie).
+2. Accept-Language header (server-side).
+3. Navigator.language (client-side).
+4. Geo-IP lookup (least reliable).
+5. Default locale (en).
+
+**Rules:**
+- Let users override detected locale at any time.
+- Persist user choice across sessions.
+- URL strategy: subdomain (fr.app.com) or path prefix (/fr/dashboard).
+
+### RTL layout support
+
+**CSS logical properties (mandatory):**
+- Use `margin-inline-start` not `margin-left`.
+- Use `padding-inline-end` not `padding-right`.
+- Use `inset-inline-start` not `left`.
+- Use `border-inline-start` not `border-left`.
+
+**HTML:**
+- Set `dir="rtl"` on the `<html>` element based on locale.
+- Use `dir="auto"` on user-generated content.
+
+**Icons and images:**
+- Mirror directional icons (arrows, progress indicators) in RTL.
+- Do NOT mirror: logos, clocks, phone icons, checkmarks.
+
+### Number and date formatting
+
+**Always use Intl APIs:**
+```javascript
+// Numbers
+new Intl.NumberFormat(locale, { style: 'currency', currency: 'USD' }).format(amount);
+
+// Dates
+new Intl.DateTimeFormat(locale, { dateStyle: 'long', timeStyle: 'short' }).format(date);
+
+// Relative time
+new Intl.RelativeTimeFormat(locale, { numeric: 'auto' }).format(-1, 'day');
+```
+
+**Rules:**
+- Never manually format numbers or dates with string templates.
+- Store dates in UTC, display in user's timezone.
+- Currency display must respect locale (symbol position, separator).
+
+### Translation management
+
+- Use a translation management system (Crowdin, Lokalise, Phrase) for professional translations.
+- Extract new keys automatically from code (i18next-parser, formatjs extract).
+- CI check: fail if base locale has keys missing from other locales.
+- Pseudo-localization in development to catch hardcoded strings and layout overflow.
+
+## Self-check before task completion
+- [ ] Did I follow the mandatory actions for this skill?
+- [ ] Did I apply the patterns appropriate to the context?
+- [ ] Did I verify the implementation meets the criteria above?
+- [ ] Did I document decisions and trade-offs made?

package/.mindforge/skills/idempotency-patterns/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: idempotency-patterns
+version: 1.0.0
+min_mindforge_version: 10.0.9
+status: stable
+triggers: idempotency pattern, idempotency key, exactly once semantic, deduplication strategy, replay safety, idempotent consumer, idempotent api, request deduplication, operation retry safety, duplicate detection, idempotent write, at-most-once processing
+---
+
+# Skill — Idempotency Patterns
+
+## When this skill activates
+Any task involving idempotent API design, idempotency keys, exactly-once semantics,
+deduplication, replay safety, or retry-safe operations.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+1. Identify which operations MUST be idempotent (any retryable operation).
+2. Determine key strategy (client-generated UUID in header).
+3. Choose storage backend (Redis for short-lived, DB for permanent records).
+
+### During implementation
+- Accept keys via `Idempotency-Key` header on all POST endpoints.
+- Store complete response with the key (status + body, not just success flag).
+- Set appropriate TTL on idempotency records.
+- Handle concurrent duplicates (lock or 409 Conflict).
+
+### After implementation
+- Test concurrent duplicate requests (race condition safety).
+- Verify partial failures are NOT cached (only complete operations).
+- Document which endpoints are idempotent and key requirements.
+
+## Core Flow
+
+```
+1. Receive request with Idempotency-Key
+2. Key exists in store? → YES: return cached response. NO: continue.
+3. Lock key (prevent concurrent processing of same key)
+4. Execute operation
+5. Store: key → {status_code, body, created_at}
+6. Release lock, return response
+```
+
+## Idempotency Key Design
+- Client-generated UUID v4 or ULID. Same key = same intended operation.
+- Scope per-endpoint AND per-user: `idempotency:{user}:{endpoint}:{key}`.
+- Max length: 255 chars. Stable across retries of same business action.
+
+## Storage Options
+
+- **Redis**: fast, TTL built-in, atomic via Lua. Use for API requests (24h TTL).
+- **Database**: durable, queryable. Use for financial/audit operations. Needs cleanup job.
+
+## Database Patterns
+
+- **INSERT ON CONFLICT DO NOTHING**: safe insert, check RETURNING for duplicate.
+- **Conditional UPDATE**: `WHERE version = $expected` — 0 rows = stale (reject).
+- **Transactional Outbox**: atomically persist state + event, poll and publish.
+
+## Consumer Idempotency
+- Dedup table: `processed_events(event_id PK, processed_at)`.
+- Flow: check if processed → BEGIN → process → INSERT dedup → COMMIT → ACK.
+- TTL: retain dedup records for broker retention + buffer (e.g., 14 days).
+
+## API Design
+
+- **GET/PUT/DELETE**: naturally idempotent (safe to retry without keys).
+- **POST/PATCH**: require explicit `Idempotency-Key` header.
+- Response headers: `Idempotent-Replayed: true` for cached responses.
+
+## Error Handling
+- 4xx client errors: cache (client should not retry same bad input).
+- 5xx server errors: do NOT cache (may succeed on retry).
+- Partial completion: do NOT cache (delete record, retry from scratch).
+
+## Self-check before task completion
+
+- [ ] Are idempotency keys accepted on all non-idempotent endpoints?
+- [ ] Is the complete response cached (status + body)?
+- [ ] Are concurrent duplicates handled safely (lock or 409)?
+- [ ] Is TTL set appropriately on idempotency records?
+- [ ] Are server errors excluded from caching?
+- [ ] Are DB writes using conflict-safe patterns?
+- [ ] Are message consumers deduplicating by event ID?

package/.mindforge/skills/incident-communication/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: incident-communication
+version: 1.0.0
+min_mindforge_version: 10.3.0
+status: stable
+triggers: incident communication, war room coordination, customer incident message, postmortem facilitation, blameless culture, incident status page, outage communication, stakeholder notification incident, incident timeline, root cause communication, severity classification, incident bridge
+compose:
+  - incident-management
+---
+
+# Incident Communication
+
+## When this skill activates
+
+This skill activates during production incidents when coordinating war rooms, writing customer-facing incident messages, updating status pages, communicating to stakeholders, facilitating postmortems, or establishing blameless culture. It applies to on-call engineers, incident commanders, and engineering managers responsible for incident response and communication.
+
+## Mandatory actions when this skill is active
+
+### Before incident communication begins
+
+1. **Classify severity immediately** — SEV1 (business-critical service down), SEV2 (degraded performance, partial outage), SEV3 (minor issue, workaround available), SEV4 (cosmetic issue, no user impact). Severity determines communication cadence and escalation.
+2. **Assign roles explicitly** — Incident Commander (coordinates response), Communications Lead (stakeholder updates), Tech Lead (drives technical resolution), Scribe (documents timeline). Ambiguous roles cause chaos.
+3. **Establish communication channels** — War room (Slack/Teams/Zoom for internal), status page (for customers), stakeholder channel (for execs/product). Don't mix internal and external comms.
+4. **Start the incident timeline immediately** — Document: when did it start, when was it detected, who's working on it, what's been tried, what's the current status. Real-time notes prevent memory loss.
+
+### During incident response
+
+#### War Room Coordination
+
+- **Run structured check-ins every 15-30 minutes** — Incident Commander asks: (1) What's the current status? (2) What are we trying next? (3) Do we need more people? Prevents chaos and ensures everyone is aligned.
+- **Use threaded communication** — Main channel for status updates only. Threads for technical debugging. Don't pollute the main channel with noisy debugging logs.
+- **Limit the war room to essential people** — Too many cooks slow resolution. Core team: 3-5 people. Observers can follow in a read-only channel.
+- **Escalate when stuck** — If the team is stuck for >30 minutes, escalate. Call in the architect, the team that owns the upstream service, or the engineer who built the system. Ego has no place in incidents.
+- **Declare resolution criteria upfront** — What does "fixed" mean? Service is healthy? All users can transact? Error rate below threshold? Prevents premature "all clear" declarations.
+
+#### Customer-Facing Communication
+
+- **Acknowledge fast, diagnose later** — Within 15 minutes of detection, post to status page: "We are investigating reports of [service] being unavailable. Updates to follow." Don't wait for root cause.
+- **Use the 3-part update structure** — (1) Current status (what's broken), (2) Customer impact (what can't they do), (3) Next steps (when's the next update). No jargon, no excuses.
+- **Update cadence by severity** — SEV1: every 30 minutes. SEV2: every 60 minutes. SEV3: every 2 hours. Customers hate silence more than bad news.
+- **Avoid over-promising** — Don't say "Fixed in 10 minutes" if you're unsure. Say "Actively working on resolution. Next update in 30 minutes."
+- **Post resolution message** — Once resolved, post: what broke, how long it lasted, how many users were impacted, what we did to fix it, what we're doing to prevent recurrence. Transparency builds trust.
+
+#### Stakeholder Notification
+
+- **Notify executives immediately for SEV1** — Execs need to know ASAP, especially if customers are complaining or revenue is impacted. One-line summary: "Service X is down. Y% of users impacted. We're on it."
+- **Use BLUF (Bottom Line Up Front)** — Don't bury the lede. "The payment service is down" comes before "We suspect a database connection pool exhaustion."
+- **Provide ETA cautiously** — If you estimate 2 hours to fix, tell stakeholders 3-4 hours. Better to resolve early than overpromise and underdeliver.
+- **Summarize after resolution** — Once the incident is resolved, send a concise executive summary: what broke, how long, customer impact, resolution, next steps. Save the detailed RCA for the postmortem.
+
+#### Incident Timeline Documentation
+
+- **Scribe logs everything in real-time** — Timestamp every key event: detection, escalation, hypothesis tested, mitigation applied, resolution. Future-you will thank present-you.
+- **Capture decisions and reasoning** — Don't just log "Rolled back to v1.3." Log "Rolled back to v1.3 because v1.4 introduced N+1 query causing DB saturation."
+- **Include dead ends** — Document failed attempts: "Restarted service at 10:15am. Did not resolve issue." Prevents repeating failed approaches.
+- **Link to relevant artifacts** — Logs, dashboards, PRs, alerts. Timeline should be a navigation hub, not a standalone document.
+
+#### Root Cause Communication
+
+- **Distinguish proximate cause from root cause** — Proximate: "The database ran out of connections." Root: "We didn't set a connection pool limit, so a spike in traffic exhausted connections." Root cause prevents recurrence.
+- **Use the Five Whys** — Why did X happen? Because Y. Why did Y happen? Because Z. Repeat 5 times until you reach the systemic failure, not the surface symptom.
+- **Avoid blame in RCA communication** — Don't say "Engineer A deployed bad code." Say "A deployment bypassed our automated testing due to a gap in CI pipeline." Focus on systems, not individuals.
+- **Define prevention actions** — Every RCA must end with: what are we doing to prevent this from happening again? Action items with owners and deadlines.
+
+#### Blameless Culture
+
+- **Assume good intent** — Engineers don't cause incidents on purpose. Treat incidents as learning opportunities, not witch hunts.
+- **Focus on systems, not people** — If one engineer's mistake caused an outage, the real failure is the system that allowed a single mistake to cascade. Fix the system.
+- **Celebrate transparency** — When someone admits a mistake, praise their honesty. If people fear punishment, they hide mistakes until they explode.
+- **Conduct blameless postmortems** — Postmortem facilitator enforces: no blame, no naming individuals (unless volunteering credit), focus on system improvements. If someone says "X person messed up," redirect: "What system gap allowed this to happen?"
+
+#### Postmortem Facilitation
+
+- **Schedule postmortem within 3-5 days** — Too soon: emotions are high, data is incomplete. Too late: memory fades, urgency disappears.
+- **Invite all incident responders + key stakeholders** — Engineers who responded, on-call rotation, product/exec if customer-facing.
+- **Use a structured template** — Summary, Timeline, Root Cause Analysis, What Went Well, What Went Poorly, Action Items (with owners and deadlines). Don't free-form it.
+- **Timebox to 1 hour** — Longer meetings lose focus. If you can't cover it in 1 hour, schedule a follow-up.
+- **Publish postmortem widely** — Share in engineering all-hands, team wikis, or public blog (if appropriate). Transparency accelerates learning across the org.
+
+### After incident resolution
+
+- **Close the loop with customers** — If customers were impacted, follow up: apologize, explain what broke, what you're doing to prevent recurrence. Consider service credits if appropriate.
+- **Track action items to completion** — 70% of postmortem action items don't get done. Assign a DRI (Directly Responsible Individual) and review progress in sprint planning.
+- **Measure incident response effectiveness** — Track: detection time, resolution time, communication cadence, customer satisfaction. Improve the metrics that matter.
+- **Update runbooks** — Every incident reveals gaps in runbooks. After resolution, update the runbook so future responders have better context.
+
+## Self-check before task completion
+
+- [ ] Severity is classified (SEV1-4) and roles are assigned (IC, Comms Lead, Tech Lead, Scribe)
+- [ ] War room check-ins happen every 15-30 minutes with structured updates
+- [ ] Customer-facing communication acknowledges the issue within 15 minutes
+- [ ] Status page updates use 3-part structure (status, impact, next steps) with no jargon
+- [ ] Incident timeline is documented in real-time with timestamps and decisions
+- [ ] Root cause distinguishes proximate cause from systemic root cause
+- [ ] Postmortem is scheduled within 3-5 days and uses blameless facilitation
+- [ ] Action items from postmortem have owners, deadlines, and are tracked to completion

package/.mindforge/skills/incident-management/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: incident-management
+version: 1.0.0
+min_mindforge_version: 10.0.7
+status: stable
+triggers: incident management process, runbook authoring, severity classification framework, communication template design, on-call rotation design, escalation path design, blameless postmortem facilitation, incident timeline reconstruction, incident playbook, war room methodology, incident retrospective framework, pager rotation scheduling
+compose:
+  - observability-stack
+---
+
+# Incident Management
+
+## When this skill activates
+
+This skill activates when the user is designing, implementing, or improving incident
+management processes. This includes severity classification frameworks, runbook
+authoring, on-call rotation scheduling, escalation path design, blameless postmortem
+facilitation, war room methodology, communication templates for stakeholders, and
+incident timeline reconstruction for retrospectives.
+
+## Mandatory actions
+
+### Before
+
+1. Identify the current incident management maturity (ad-hoc, documented, measured, optimized).
+2. Determine the team size, timezone coverage, and existing on-call tooling (PagerDuty, Opsgenie, etc.).
+3. Assess existing runbook coverage and documentation gaps.
+4. Review past incident frequency and mean-time-to-recovery (MTTR) trends.
+5. Confirm observability stack integration (alerts feed into incident workflow).
+
+### During
+
+**Severity Framework:**
+- **SEV1 (Critical):** Total service outage affecting all users. Revenue impact. All-hands response. Target acknowledgment: 5 minutes. Target resolution: 1 hour.
+- **SEV2 (Major):** Significant degradation affecting many users. Key features unavailable. On-call + escalation. Target acknowledgment: 15 minutes. Target resolution: 4 hours.
+- **SEV3 (Minor):** Partial degradation affecting a subset of users. Workarounds exist. On-call handles. Target acknowledgment: 30 minutes. Target resolution: 24 hours.
+- **SEV4 (Low):** Minor issue with minimal user impact. Handled during business hours. Target resolution: 72 hours.
+- Severity is determined by impact (users affected) x urgency (revenue/safety/compliance risk).
+
+**Runbook Template:**
+- **Trigger Conditions:** What alert or symptom initiates this runbook.
+- **Investigation Steps:** Ordered diagnostic commands and checks (copy-pasteable).
+- **Mitigation Actions:** Immediate steps to restore service (rollback, failover, scale).
+- **Escalation Criteria:** When to involve additional teams or bump severity.
+- **Communication Templates:** Pre-written status page updates and stakeholder messages.
+- **Verification:** How to confirm the incident is resolved.
+- Keep runbooks in version control, review quarterly, update after every incident.
+
+**On-Call Rotation:**
+- Follow-the-sun model for distributed teams (no one owns overnight).
+- Maximum rotation length: 1 week. Longer causes burnout.
+- Provide compensation (extra pay, time off, or both).
+- Escalation after 15 minutes of no acknowledgment.
+- Secondary on-call as backup for every primary.
+- On-call handoff includes open incidents, recent changes, and known risks.
+
+**War Room Methodology:**
+- Designate an Incident Commander (IC) who coordinates, does not debug.
+- IC assigns roles: Communications Lead, Technical Lead, Scribe.
+- Communication cadence: status page updates every 15 minutes during SEV1/SEV2.
+- Use a shared channel (Slack/Teams) with pinned timeline.
+- No blame during active incident — focus on mitigation only.
+
+**Postmortem Structure:**
+- **Timeline:** Minute-by-minute reconstruction of events.
+- **Impact:** Users affected, duration, revenue/SLA impact.
+- **Root Cause:** The systemic failure that allowed the incident.
+- **Contributing Factors:** What made detection/resolution harder.
+- **Action Items:** Specific, assigned, time-boxed improvements.
+- Blameless: focus on systems and processes, never individuals.
+- Share postmortems broadly — learning is organizational.
+- Track action item completion rate as a metric.
+
+**Communication:**
+- Status page updates every 15 minutes during active incidents.
+- Internal stakeholder updates via designated channel.
+- Customer-facing communication: acknowledge → investigate → mitigate → resolve.
+- Post-resolution: summary email with impact and next steps.
+
+### After
+
+1. Verify runbooks are tested (tabletop exercises quarterly).
+2. Confirm escalation paths are current and contact information is valid.
+3. Validate on-call schedule has no coverage gaps.
+4. Review postmortem action item completion from previous incidents.
+5. Measure MTTR trends and identify systemic improvement opportunities.
+
+## Self-check before task completion
+
+- [ ] Severity levels are clearly defined with response time targets.
+- [ ] Runbooks follow the template and are actionable (copy-pasteable commands).
+- [ ] On-call rotation is sustainable (max 1 week, compensation, follow-the-sun).
+- [ ] Escalation paths have timeout-based auto-escalation.
+- [ ] Postmortem template is blameless and includes action items.
+- [ ] Communication cadence is defined for each severity level.
+- [ ] All processes integrate with existing alerting and observability tooling.
+- [ ] Quarterly review cadence is established for runbook freshness.