arkaos 2.0.0 → 2.0.1

package/departments/dev/skills/dependency-audit/references/license-matrix.md

@@ -0,0 +1,191 @@
+# Open Source License Compatibility Matrix — Deep Reference
+
+> Companion to `dependency-audit/SKILL.md`. License obligations, compatibility rules, and commercial implications.
+
+## License Classification
+
+| License | Type | OSI Approved | Copyleft Strength |
+|---------|------|-------------|-------------------|
+| MIT | Permissive | Yes | None |
+| ISC | Permissive | Yes | None |
+| BSD-2-Clause | Permissive | Yes | None |
+| BSD-3-Clause | Permissive | Yes | None |
+| Apache-2.0 | Permissive | Yes | None (patent grant) |
+| MPL-2.0 | Weak copyleft | Yes | File-level |
+| LGPL-2.1 | Weak copyleft | Yes | Library-level |
+| LGPL-3.0 | Weak copyleft | Yes | Library-level |
+| GPL-2.0 | Strong copyleft | Yes | Entire work |
+| GPL-3.0 | Strong copyleft | Yes | Entire work |
+| AGPL-3.0 | Network copyleft | Yes | Entire work + network use |
+| SSPL | Source-available | No | Entire service stack |
+| BSL 1.1 | Source-available | No | Time-delayed open source |
+| Proprietary | Proprietary | No | Full restriction |
+
+## Compatibility Matrix
+
+Can you combine code under these licenses in the SAME project?
+
+| Dependency License | Your Project: MIT | Your Project: Apache-2.0 | Your Project: GPL-3.0 | Your Project: Proprietary |
+|-------------------|:-:|:-:|:-:|:-:|
+| MIT | OK | OK | OK | OK |
+| BSD-2/3 | OK | OK | OK | OK |
+| Apache-2.0 | OK | OK | OK | OK |
+| MPL-2.0 | OK (keep MPL files) | OK (keep MPL files) | OK | OK (keep MPL files) |
+| LGPL-2.1/3.0 | OK (dynamic link) | OK (dynamic link) | OK | OK (dynamic link only) |
+| GPL-2.0 | NO | NO | OK (if "or later") | NO |
+| GPL-3.0 | NO | NO | OK | NO |
+| AGPL-3.0 | NO | NO | OK (becomes AGPL) | NO |
+
+**Key:** OK = compatible. NO = license violation.
+
+## Obligations by License
+
+### Permissive Licenses (MIT, BSD, ISC, Apache-2.0)
+
+| Obligation | MIT | BSD-2 | BSD-3 | Apache-2.0 |
+|------------|:---:|:-----:|:-----:|:----------:|
+| Include copyright notice | Yes | Yes | Yes | Yes |
+| Include license text | Yes | Yes | Yes | Yes |
+| State changes | No | No | No | Yes |
+| Patent grant | No | No | No | Yes |
+| No endorsement clause | No | No | Yes | No |
+| NOTICE file preservation | No | No | No | Yes |
+
+### Copyleft Licenses (MPL, LGPL, GPL, AGPL)
+
+| Obligation | MPL-2.0 | LGPL-3.0 | GPL-3.0 | AGPL-3.0 |
+|------------|:-------:|:--------:|:-------:|:--------:|
+| Source code of modified files | Yes | Yes | Yes | Yes |
+| Source code of entire work | No | No | Yes | Yes |
+| Network use triggers copyleft | No | No | No | Yes |
+| Allow reverse engineering | No | Yes | Yes | Yes |
+| Provide installation info | No | No | Yes | Yes |
+| Anti-tivoization clause | No | No | Yes | Yes |
+
+## Commercial Use Decision Tree
+
+```
+START: Is the dependency's license identified?
+  NO  --> STOP. Do not use. Unknown license = all rights reserved.
+  YES --> Is it permissive (MIT, BSD, ISC, Apache)?
+    YES --> SAFE for commercial use. Include attribution.
+    NO  --> Is it weak copyleft (MPL, LGPL)?
+      YES --> SAFE if:
+        MPL: Keep modified MPL files open-source
+        LGPL: Dynamic linking only (no static linking in proprietary)
+      NO  --> Is it strong copyleft (GPL)?
+        YES --> NOT SAFE for proprietary. Your entire project becomes GPL.
+               Exception: GPL with Classpath Exception (like OpenJDK)
+        NO  --> Is it network copyleft (AGPL)?
+          YES --> NOT SAFE. Even SaaS use triggers copyleft.
+          NO  --> Is it source-available (SSPL, BSL)?
+            YES --> Review specific terms. Usually NOT safe for competing services.
+            NO  --> Legal review required.
+```
+
+## Common Ecosystem License Risks
+
+### Node.js (npm)
+
+| Risk Pattern | Example | Action |
+|-------------|---------|--------|
+| Transitive GPL dependency | `node-sass` (deprecated, had GPL deps) | Audit full tree with `license-checker` |
+| License field missing in package.json | Small utilities | Check source repo manually |
+| "SEE LICENSE IN" custom file | Some enterprise libs | Read the actual file |
+| Dual license with one GPL option | Some databases | Verify you are using the permissive option |
+
+### PHP (Composer)
+
+| Risk Pattern | Example | Action |
+|-------------|---------|--------|
+| Laravel itself is MIT | Framework code | Safe |
+| Packages wrapping GPL tools | ImageMagick bindings | Check if wrapper license differs from tool |
+| WordPress ecosystem (GPL-2.0+) | Themes, plugins | All derivatives must be GPL |
+
+### Python (pip)
+
+| Risk Pattern | Example | Action |
+|-------------|---------|--------|
+| PSF license (Python itself) | Standard lib | Safe, permissive |
+| LGPL in scientific computing | Some NumPy deps historically | Dynamic linking usually fine |
+| GPL in CLI tools used via subprocess | `pandoc` (GPL) | Subprocess call != linking (generally safe) |
+
+## Dual Licensing Strategies
+
+| Strategy | How It Works | Example |
+|----------|-------------|---------|
+| Open core | AGPL for community, proprietary for enterprise | MongoDB (was AGPL, now SSPL) |
+| GPL + commercial | GPL for open use, paid license for proprietary embedding | MySQL, Qt |
+| MIT + paid support | MIT code, paid for SLA/support/features | Many SaaS tools |
+| BSL time-delay | Source-available now, becomes open source after N years | CockroachDB, Sentry |
+
+## License Audit Automation
+
+### npm
+
+```bash
+# List all licenses
+npx license-checker --summary
+
+# Fail CI on copyleft
+npx license-checker --failOn "GPL-2.0;GPL-3.0;AGPL-3.0"
+
+# Export for legal review
+npx license-checker --csv --out licenses.csv
+```
+
+### Composer (PHP)
+
+```bash
+# List licenses
+composer licenses
+
+# Detailed with dependencies
+composer licenses --format=json
+```
+
+### pip (Python)
+
+```bash
+pip-licenses --format=table --with-urls
+pip-licenses --fail-on="GPL-2.0;GPL-3.0;AGPL-3.0"
+```
+
+## License Change Risks
+
+| Event | Risk | Action |
+|-------|------|--------|
+| Maintainer relicenses (MIT -> BSL) | Future versions restricted | Pin to last MIT version |
+| CLA-based project changes license | All contributor code affected | Monitor project governance |
+| Acquisition changes license | New owner may restrict | Evaluate fork options |
+| License removed from package | Defaults to all-rights-reserved | Contact maintainer, find alternative |
+
+### Notable License Changes (Precedents)
+
+| Project | From | To | Year | Impact |
+|---------|------|----|------|--------|
+| Elasticsearch | Apache-2.0 | SSPL | 2021 | AWS forked as OpenSearch |
+| Redis modules | BSD | SSPL | 2024 | Community forks (Valkey) |
+| HashiCorp (Terraform) | MPL-2.0 | BSL 1.1 | 2023 | OpenTofu fork |
+| MongoDB | AGPL-3.0 | SSPL | 2018 | Cloud providers stopped offering |
+
+## NOTICE File Template
+
+When using Apache-2.0 licensed code, preserve and extend the NOTICE file:
+
+```
+This product includes software developed by [Original Author].
+Licensed under the Apache License, Version 2.0.
+
+Modifications by [Your Company], [Year].
+```
+
+## Quick Reference: "Can I Use This?"
+
+| Your Project Type | Safe Licenses | Caution | Blocked |
+|-------------------|--------------|---------|---------|
+| Proprietary SaaS | MIT, BSD, ISC, Apache-2.0 | MPL, LGPL (check linking) | GPL, AGPL, SSPL |
+| Proprietary desktop app | MIT, BSD, ISC, Apache-2.0 | LGPL (dynamic link only) | GPL, AGPL |
+| Open source (MIT) | MIT, BSD, ISC, Apache-2.0 | MPL | GPL, AGPL (would change your license) |
+| Open source (GPL-3.0) | All OSI-approved | SSPL, BSL | Proprietary, GPL-2.0-only |
+| Internal tool (never distributed) | All (copyleft not triggered) | AGPL (network use triggers) | SSPL (service use triggers) |

package/departments/dev/skills/incident/SKILL.md

@@ -123,3 +123,7 @@ Surface these issues WITHOUT being asked:
 1. [Key takeaway]
 2. [Key takeaway]
 ```
+
+## References
+
+- [severity-playbook.md](references/severity-playbook.md) — SEV1-4 definitions, escalation paths, communication templates, and PIR checklist

package/departments/dev/skills/incident/references/severity-playbook.md

@@ -0,0 +1,221 @@
+# Severity Playbook — Deep Reference
+
+> SEV1-4 definitions, escalation paths, communication templates, PIR framework, and anti-patterns.
+
+## Severity Definitions with Examples
+
+| Level | Definition | User Impact | Examples |
+|-------|-----------|-------------|---------|
+| **SEV1** | Complete service outage, data loss, active security breach | 100% of users or data integrity compromised | Database corruption, payment system down, credentials leaked, entire site 500 |
+| **SEV2** | Major feature degraded, >25% users affected | Significant functionality lost | Search broken, checkout intermittent, API latency >10x, auth failures for subset |
+| **SEV3** | Single feature broken, workaround exists | Minor inconvenience, <10% users | Export fails (manual workaround), slow dashboard, broken notification emails |
+| **SEV4** | Cosmetic, dev/staging only, no user impact | None or negligible | UI alignment bug, staging env down, deprecation warning, flaky test |
+
+## Escalation Paths
+
+### SEV1 — Full Escalation
+
+```
+T+0min    Alert fires or report received
+T+5min    On-call engineer acknowledges, starts investigation
+T+10min   Incident Commander assigned, war room opened
+T+15min   First stakeholder notification sent
+T+15min   Engineering lead and CTO notified
+T+30min   If no mitigation path: escalate to vendor/cloud provider
+T+60min   If unresolved: executive briefing, consider public status page
+T+4h      If unresolved: assemble cross-team tiger team
+```
+
+### SEV2 — Team Escalation
+
+```
+T+0min    Alert fires or report received
+T+15min   On-call engineer acknowledges
+T+30min   Team lead notified, incident channel created
+T+1h      First stakeholder update
+T+2h      If unresolved: escalate to engineering manager
+T+4h      If unresolved: consider SEV1 upgrade
+```
+
+### SEV3 — Standard Response
+
+```
+T+0min    Ticket created automatically or manually
+T+2h      Engineer assigned during business hours
+T+1d      Initial investigation and fix ETA
+T+3d      Fix deployed or workaround documented
+```
+
+### SEV4 — Backlog
+
+```
+T+0min    Ticket created, tagged low priority
+Next sprint  Triaged and prioritized
+```
+
+## Severity Upgrade/Downgrade Criteria
+
+| Trigger | Action |
+|---------|--------|
+| Impact expands beyond initial scope | Upgrade severity |
+| Duration exceeds 2x expected MTTR | Upgrade severity |
+| Data integrity concerns emerge | Upgrade to SEV1 |
+| Workaround found and confirmed | Consider downgrade |
+| Impact narrower than initial assessment | Downgrade severity |
+
+## Communication Templates
+
+### Initial Notification (SEV1/SEV2)
+
+```
+INCIDENT: [SEV{N}] {Service Name} - {Brief Description}
+
+Impact: {What users experience, how many affected}
+Start time: {ISO 8601 timestamp, timezone}
+Status: INVESTIGATING
+
+Incident Commander: {Name}
+Technical Lead: {Name}
+War Room: {Slack channel / Zoom link}
+
+Next update: {Time, max 15min for SEV1, 30min for SEV2}
+```
+
+### Status Update
+
+```
+INCIDENT UPDATE #{N}: [SEV{level}] {Service Name}
+
+Status: INVESTIGATING | IDENTIFIED | MITIGATING | MONITORING | RESOLVED
+Duration: {elapsed time}
+
+What we know:
+- {Finding 1}
+- {Finding 2}
+
+Actions taken:
+- {Action 1}
+- {Action 2}
+
+Next steps:
+- {Planned action with owner}
+
+ETA to resolution: {estimate or "Under investigation"}
+Next update: {time}
+```
+
+### Resolution Notification
+
+```
+RESOLVED: [SEV{level}] {Service Name} - {Brief Description}
+
+Duration: {start} to {end} ({total})
+Root cause: {1-2 sentence summary}
+Fix applied: {what was done}
+Users affected: {count or percentage}
+
+Post-Incident Review scheduled: {date/time}
+Action items will be tracked in: {ticket link}
+```
+
+### Customer-Facing Status Page
+
+```
+[Investigating] We are aware of issues with {feature}. Our team is actively
+investigating. We will provide an update within {timeframe}.
+
+[Identified] We have identified the cause of {issue}. A fix is being implemented.
+Expected resolution: {ETA}.
+
+[Resolved] The issue with {feature} has been resolved. All systems are operating
+normally. We apologize for the inconvenience.
+```
+
+## Post-Incident Review (PIR) Template
+
+### Header
+
+| Field | Value |
+|-------|-------|
+| Incident ID | INC-YYYY-NNN |
+| Severity | SEV{N} |
+| Date | YYYY-MM-DD |
+| Duration | {start} to {end} ({total}) |
+| Incident Commander | {Name} |
+| Technical Lead | {Name} |
+| PIR Author | {Name} |
+| PIR Date | {date, within 48h of resolution} |
+
+### Timeline (Required for SEV1/SEV2)
+
+| Time (UTC) | Event | Source |
+|------------|-------|--------|
+| HH:MM | Alert fired: {description} | Monitoring |
+| HH:MM | On-call acknowledged | PagerDuty |
+| HH:MM | IC assigned, war room opened | Manual |
+| HH:MM | Root cause identified: {description} | Investigation |
+| HH:MM | Mitigation applied: {action} | Deployment |
+| HH:MM | Service confirmed restored | Monitoring |
+
+### Root Cause Analysis
+
+**5 Whys format:**
+
+```
+1. Why did the service go down?
+   -> Database connection pool exhausted
+2. Why was the pool exhausted?
+   -> Slow query holding connections for 30s+
+3. Why was the query slow?
+   -> Missing index on users.email after migration
+4. Why was the index missing?
+   -> Migration script did not include index creation
+5. Why was the missing index not caught?
+   -> No performance test in CI for migration scripts
+```
+
+### Action Items Table
+
+| # | Action | Type | Owner | Due Date | Priority | Status |
+|---|--------|------|-------|----------|----------|--------|
+| 1 | Add index on users.email | Fix | {name} | {date} | P0 | Done |
+| 2 | Add migration perf tests to CI | Prevent | {name} | {date} | P1 | Open |
+| 3 | Add connection pool alert at 80% | Detect | {name} | {date} | P1 | Open |
+| 4 | Document DB migration checklist | Process | {name} | {date} | P2 | Open |
+
+Action item types: **Fix** (address this incident), **Prevent** (stop recurrence), **Detect** (catch it earlier), **Process** (improve response).
+
+## PIR Quality Checklist
+
+- [ ] Timeline is complete with timestamps from monitoring (not memory)
+- [ ] Root cause goes deep enough (5 Whys or equivalent)
+- [ ] Action items have owners and due dates (no orphaned items)
+- [ ] Action items include detection improvements, not just fixes
+- [ ] Blameless language throughout (systems, not people)
+- [ ] Shared with broader engineering team
+- [ ] Runbooks updated with new knowledge
+- [ ] Follow-up review scheduled for action item completion
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It Hurts | Fix |
+|-------------|-------------|-----|
+| Skipping severity classification | Wrong response level, wasted effort or delayed response | Classify within first 5 minutes, always |
+| Hero culture (one person does everything) | Burnout, no knowledge sharing, SPOF | Separate IC and Tech Lead roles |
+| No communication cadence | Stakeholders assume the worst, escalate unnecessarily | Set timer for updates, even if "still investigating" |
+| Blame-focused PIR | People hide mistakes, no systemic improvement | Blameless by policy, focus on systems |
+| PIR action items with no owners | Nothing gets done, same incident recurs | Every action item requires name + date |
+| Never upgrading severity | SEV3 that is actually SEV1 gets slow response | Review upgrade criteria at every status update |
+| Fix-only action items | Catches this incident but not the next variant | Always include Detect and Prevent items |
+| PIR delayed beyond 1 week | Details forgotten, momentum lost | Schedule within 48 hours, hard deadline 5 days |
+
+## Metrics to Track
+
+| Metric | Target | Measures |
+|--------|--------|----------|
+| MTTD (Mean Time to Detect) | < 5 min | Monitoring effectiveness |
+| MTTA (Mean Time to Acknowledge) | < 10 min (SEV1) | On-call responsiveness |
+| MTTR (Mean Time to Resolve) | < 1h (SEV1), < 4h (SEV2) | Resolution efficiency |
+| PIR completion rate | 100% for SEV1/SEV2 | Learning culture |
+| Action item completion rate | > 90% within due date | Follow-through |
+| Recurrence rate | < 5% same root cause | Prevention effectiveness |

package/departments/dev/skills/observability/SKILL.md

@@ -117,3 +117,7 @@ Surface these issues WITHOUT being asked:
 2. [Next priority]
 3. [Next priority]
 ```
+
+## References
+
+- [slo-design.md](references/slo-design.md) — SLI/SLO/SLA framework, error budget calculations, and burn rate alert configuration

package/departments/dev/skills/observability/references/slo-design.md

@@ -0,0 +1,200 @@
+# SLO Design Guide — Deep Reference
+
+> SLI/SLO/SLA framework, error budgets, burn rate alerts, and production SLO documents.
+
+## Terminology
+
+| Term | Definition | Owner | Example |
+|------|-----------|-------|---------|
+| **SLI** (Service Level Indicator) | Quantitative measure of service behavior | Engineering | Request latency p99 |
+| **SLO** (Service Level Objective) | Target value for an SLI over a time window | Engineering + Product | p99 latency < 200ms over 30 days |
+| **SLA** (Service Level Agreement) | Contract with consequences for missing targets | Business + Legal | 99.9% uptime or service credits |
+| **Error Budget** | Allowed amount of unreliability | Engineering | 0.1% of requests can fail per month |
+
+Relationship: SLI measures reality. SLO sets internal targets. SLA sets external commitments. SLO should always be stricter than SLA.
+
+## Step 1: Define SLIs
+
+### SLI Selection by Service Type
+
+| Service Type | Primary SLI | Secondary SLIs |
+|-------------|------------|----------------|
+| **API / Web Service** | Availability (successful responses / total) | Latency p50/p95/p99, error rate |
+| **Data Pipeline** | Freshness (time since last successful run) | Throughput, completeness |
+| **Storage System** | Durability (data loss events) | Availability, latency |
+| **Batch Processing** | Completion rate within deadline | Processing time, error rate |
+| **Streaming** | End-to-end latency | Throughput, ordering guarantees |
+
+### SLI Specification Template
+
+```
+SLI Name: API Availability
+Definition: Proportion of valid requests served successfully
+Good event: HTTP response with status code != 5xx, latency < 1000ms
+Valid event: All HTTP requests excluding health checks
+Measurement: Load balancer access logs
+Aggregation: Rolling 30-day window
+```
+
+### Common SLI Mistakes
+
+| Mistake | Problem | Fix |
+|---------|---------|-----|
+| Using server-side metrics only | Misses client-perceived failures | Measure at the edge/load balancer |
+| Counting health checks | Inflates availability numbers | Exclude synthetic traffic |
+| Averaging latency | Hides tail latency issues | Use percentiles (p50, p95, p99) |
+| Boolean up/down | Too coarse, misses partial failures | Use request-level success ratio |
+| No "valid event" filter | Includes bot traffic, attacks | Define what counts as a real request |
+
+## Step 2: Set SLO Targets
+
+### Target Selection Guide
+
+| Availability | Downtime/Month | Downtime/Year | Typical Use Case |
+|-------------|---------------|---------------|-----------------|
+| 99% (two 9s) | 7.3 hours | 3.65 days | Internal tools, dev environments |
+| 99.5% | 3.65 hours | 1.83 days | Non-critical B2B services |
+| 99.9% (three 9s) | 43.8 minutes | 8.76 hours | Standard production services |
+| 99.95% | 21.9 minutes | 4.38 hours | Important customer-facing services |
+| 99.99% (four 9s) | 4.38 minutes | 52.6 minutes | Payment systems, auth services |
+| 99.999% (five 9s) | 26.3 seconds | 5.26 minutes | Safety-critical (rarely achievable) |
+
+### Setting Targets Checklist
+
+- [ ] Based on current performance (set SLO at current p10 performance, not aspirational)
+- [ ] Aligned with user expectations (survey or infer from behavior)
+- [ ] Achievable with current architecture (do not promise what you cannot deliver)
+- [ ] Stricter than SLA by at least 0.1% (buffer for reaction time)
+- [ ] Different SLOs for different user segments if needed (paid vs free)
+- [ ] Reviewed quarterly and adjusted based on data
+
+## Step 3: Calculate Error Budgets
+
+### Formula
+
+```
+Error Budget = 1 - SLO target
+
+Example: SLO = 99.9% availability over 30 days
+Error Budget = 0.1% = 0.001
+Total requests/month = 10,000,000
+Allowed failures = 10,000,000 * 0.001 = 10,000 failed requests
+```
+
+### Error Budget Policy
+
+| Budget Remaining | Action |
+|-----------------|--------|
+| > 50% | Normal development velocity, deploy freely |
+| 25-50% | Increased caution, review risky deployments |
+| 10-25% | Freeze non-critical deployments, focus on reliability |
+| < 10% | Emergency mode: only reliability fixes ship |
+| Exhausted (0%) | Full deployment freeze until budget recovers |
+
+### Budget Consumption Tracking
+
+```
+Daily budget = Error Budget / 30
+Burn rate = actual_errors / expected_daily_budget
+
+Burn rate = 1.0: consuming budget exactly as planned
+Burn rate > 1.0: consuming faster than sustainable
+Burn rate = 10.0: will exhaust 30-day budget in 3 days
+```
+
+## Step 4: Configure Burn Rate Alerts
+
+### Multi-Window Burn Rate Alerting
+
+| Alert | Burn Rate | Long Window | Short Window | Severity | Budget Consumed |
+|-------|-----------|-------------|-------------|----------|-----------------|
+| **Page (SEV1)** | 14.4x | 1 hour | 5 min | Critical | 2% in 1h |
+| **Page (SEV2)** | 6x | 6 hours | 30 min | High | 5% in 6h |
+| **Ticket** | 3x | 3 days | 6 hours | Medium | 10% in 3d |
+| **Ticket** | 1x | 30 days | 3 days | Low | Budget tracking |
+
+### Why Multi-Window?
+
+- **Long window** prevents alerting on brief spikes (high precision)
+- **Short window** catches sudden onset (low detection time)
+- Both conditions must be true simultaneously to fire
+
+### Alert Configuration Example (Prometheus)
+
+```yaml
+# SEV1: 14.4x burn rate over 1h, confirmed by 5min window
+- alert: SLOBurnRateCritical
+  expr: |
+    (
+      sum(rate(http_requests_total{code=~"5.."}[1h]))
+      / sum(rate(http_requests_total[1h]))
+    ) > (14.4 * 0.001)
+    AND
+    (
+      sum(rate(http_requests_total{code=~"5.."}[5m]))
+      / sum(rate(http_requests_total[5m]))
+    ) > (14.4 * 0.001)
+  for: 2m
+  labels:
+    severity: critical
+  annotations:
+    summary: "High error burn rate - SEV1"
+    budget_impact: "Will exhaust 30-day error budget in 50 hours"
+```
+
+## Step 5: Document the SLO
+
+### SLO Document Template
+
+```markdown
+# SLO: {Service Name} - {SLI Name}
+
+| Field | Value |
+|-------|-------|
+| Service | {service name} |
+| Owner | {team name} |
+| SLI | {definition} |
+| SLO Target | {percentage} over {window} |
+| SLA (if applicable) | {percentage} with {consequence} |
+| Error Budget | {number} per {period} |
+| Measurement Source | {logs / metrics / synthetic} |
+| Dashboard | {link} |
+| Alert Runbook | {link} |
+
+## SLI Definition
+Good event: {definition}
+Valid event: {definition}
+Exclusions: {health checks, synthetic monitoring, etc.}
+
+## Error Budget Policy
+{Copy from error budget policy table, customized for this service}
+
+## Review Schedule
+- Weekly: error budget consumption in standup
+- Monthly: SLO performance review
+- Quarterly: SLO target adjustment if needed
+```
+
+## Common Mistakes
+
+| Mistake | Why It Hurts | Fix |
+|---------|-------------|-----|
+| SLO = 100% | Zero error budget, no deployments possible | Start at 99.9%, adjust based on data |
+| SLO set without measurement | Cannot track compliance | Implement SLI measurement first |
+| Same SLO for all services | Over-invests in non-critical, under-invests in critical | Tier services, different SLOs per tier |
+| No error budget policy | SLO exists but nobody acts on it | Define actions per budget threshold |
+| Alerting on SLI instead of burn rate | Too noisy (brief spikes trigger) | Use multi-window burn rate alerts |
+| SLO not reviewed | Target drifts from reality | Quarterly review cadence |
+| SLA stricter than SLO | No reaction time before breach | SLO should be 0.1-0.5% stricter than SLA |
+| Too many SLOs per service | Focus diluted, alert fatigue | 1-3 SLOs per service maximum |
+
+## SLO Maturity Model
+
+| Level | Characteristics | Next Step |
+|-------|----------------|-----------|
+| **0 - None** | No SLIs or SLOs defined | Define 1 SLI per critical service |
+| **1 - Measured** | SLIs exist, dashboards built | Set SLO targets based on current performance |
+| **2 - Targeted** | SLOs set, error budgets calculated | Implement burn rate alerts |
+| **3 - Alerted** | Multi-window burn rate alerts active | Define error budget policy |
+| **4 - Managed** | Error budget drives deployment decisions | Automate deployment freeze on budget exhaustion |
+| **5 - Optimized** | SLOs reviewed quarterly, drive architecture decisions | Tie SLOs to business KPIs |

package/departments/dev/skills/rag-architect/SKILL.md

@@ -123,3 +123,8 @@ Surface these issues WITHOUT being asked:
 - Storage: ~$X/month for <N> vectors
 - Query cost: ~$X per 1K queries
 ```
+
+## References
+
+- [chunking-strategies.md](references/chunking-strategies.md) — Decision tree and benchmarks for chunking approaches
+- [evaluation-guide.md](references/evaluation-guide.md) — RAGAS metrics and ground truth dataset creation