@decocms/start 0.19.0

package/.cursor/skills/incident-report/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: incident-report
+description: Create incident reports and post-mortems for platform issues. Supports both internal technical reports and client-facing communications. Use when documenting outages, security vulnerabilities, data leaks, performance degradation, or any production incident.
+---
+
+# Incident Report Skill
+
+Generate comprehensive incident reports and post-mortems following team standards. Supports two report types: internal technical analysis and client-facing communications.
+
+## Quick Start
+
+1. **Classify** the incident (severity, type, audience)
+2. **Gather** information using the discovery prompts
+3. **Generate** the appropriate report using templates
+4. **Review** using the checklist
+
+## Phase 1: Classification
+
+### Severity Levels
+
+| Level | Criteria | Response Time |
+|-------|----------|---------------|
+| **P0 Critical** | Data breach, cross-tenant exposure, complete outage | Immediate |
+| **P1 High** | Partial outage, significant performance degradation, security vulnerability | < 1 hour |
+| **P2 Medium** | Degraded service, non-critical feature down | < 4 hours |
+| **P3 Low** | Minor issue, cosmetic, workaround available | Next business day |
+
+### Incident Types
+
+- **Outage**: Service unavailable or severely degraded
+- **Security**: Vulnerability, unauthorized access, data exposure
+- **Data Leak**: Customer data exposed to wrong party
+- **Performance**: Latency spikes, memory issues, 5xx errors
+- **Configuration**: Misconfig causing issues, deployment failures
+
+### Report Audience
+
+| Audience | Report Type | Focus |
+|----------|-------------|-------|
+| **Internal** | Technical post-mortem | Root cause, technical details, action items |
+| **Client** | Customer communication | Impact, resolution, prevention, reassurance |
+
+## Phase 2: Information Gathering
+
+Before writing, gather these details. Ask the user if any are missing:
+
+### Core Facts (Required)
+
+```
+- Incident date and time (with timezone)
+- Duration of impact
+- Affected systems/services
+- Affected customers/sites
+- Who detected it (monitoring, customer report, internal)
+- Current status (ongoing, resolved, monitoring)
+```
+
+### Technical Details (Internal Reports)
+
+```
+- What was the root cause?
+- What was the timeline? (detection → investigation → fix → verification)
+- What commands/logs showed the issue?
+- What was the fix applied?
+- Were there any secondary effects?
+```
+
+### Impact Assessment
+
+```
+- Number of affected requests/users
+- Error rates (percentage)
+- Revenue impact (if applicable)
+- Data exposure scope (if security/data leak)
+- Customer complaints received
+```
+
+### Resolution Details
+
+```
+- What immediate fix was applied?
+- Who was involved in resolution?
+- How was the fix verified?
+- Are there follow-up actions needed?
+```
+
+## Phase 3: Generate Report
+
+### Internal Technical Report
+
+Use template: [templates/internal-report.md](templates/internal-report.md)
+
+Structure:
+1. **TL;DR** - 3-5 bullet summary for busy readers
+2. **Executive Summary** - One paragraph overview
+3. **Timeline** - Chronological events
+4. **Root Cause Analysis** - Technical deep-dive
+5. **Impact** - Quantified effects
+6. **Resolution** - What was done
+7. **Action Items** - TODO list with owners
+8. **Lessons Learned** - Blameless retrospective
+9. **References** - Links, logs, PRs
+
+### Client-Facing Report
+
+Use template: [templates/client-report.md](templates/client-report.md)
+
+Structure:
+1. **Subject Line** - Clear, professional
+2. **Acknowledgment** - We take this seriously
+3. **What Happened** - Non-technical explanation
+4. **Impact on You** - Specific to this client
+5. **Resolution** - What we did
+6. **Prevention** - What we're doing to prevent recurrence
+7. **Contact** - Who to reach for questions
+
+## Phase 4: Review Checklist
+
+Before finalizing, verify:
+
+### Content Quality
+- [ ] Timeline is accurate and complete
+- [ ] Root cause is clearly identified (not symptoms)
+- [ ] Impact is quantified with real numbers
+- [ ] Action items have owners and priorities
+- [ ] No blame assigned to individuals
+
+### Client Reports Additional
+- [ ] Technical jargon removed or explained
+- [ ] Tone is professional and empathetic
+- [ ] Next steps are clear
+- [ ] Contact information included
+- [ ] Client-specific impact addressed
+
+### Security Incidents Additional
+- [ ] Scope of exposure documented
+- [ ] Affected data types listed
+- [ ] Customer notification requirements checked
+- [ ] Compliance implications noted (LGPD, GDPR)
+
+## Blameless Post-Mortem Principles
+
+1. **Focus on systems, not people** - "The monitoring gap allowed..." not "John failed to..."
+2. **Assume good intent** - Everyone was trying to do the right thing
+3. **Learn, don't punish** - Goal is improvement, not blame
+4. **Be specific** - "Deploy at 14:32 caused..." not "Recent changes caused..."
+5. **Quantify impact** - "2% of 30k requests = 600 errors" not "some errors"
+
+## Writing Tips
+
+### For Internal Reports
+- Be technically precise
+- Include actual commands, logs, configs
+- Link to related PRs, issues, dashboards
+- Use diagrams for complex flows
+
+### For Client Reports
+- Lead with resolution/status
+- Avoid defensive language
+- Be specific about prevention measures
+- Keep under 500 words unless complex
+- Translate technical terms
+
+## File Naming Convention
+
+```
+{slug}-{YYYY-MM-DD}.md
+
+Examples:
+- istio-xds-message-overflow-2026-02-03.md
+- openbox2-traffic-spike-502-2026-02-05.md
+- aviator-cross-tenant-routing-2026-02-03.md
+```
+
+## Additional Resources
+
+- [templates/internal-report.md](templates/internal-report.md) - Full internal template
+- [templates/client-report.md](templates/client-report.md) - Client communication template
+- [references/5-whys.md](references/5-whys.md) - Root cause analysis technique

package/.cursor/skills/incident-report/references/5-whys.md

@@ -0,0 +1,75 @@
+# 5-Whys Root Cause Analysis
+
+A simple technique to find the true root cause of an incident by asking "Why?" repeatedly.
+
+## How to Use
+
+1. Start with the problem statement
+2. Ask "Why did this happen?"
+3. For each answer, ask "Why?" again
+4. Continue until you reach a root cause (usually 5 iterations)
+5. Stop when you reach something actionable
+
+## Example: Cross-Tenant Routing
+
+```
+Problem: Customer A's site showed Customer B's content
+
+Why 1: Why did Customer A see Customer B's content?
+→ Because the routing rules sent traffic to the wrong backend
+
+Why 2: Why were routing rules pointing to wrong backend?
+→ Because the Envoy proxy was using stale/outdated configuration
+
+Why 3: Why was Envoy using stale configuration?
+→ Because it couldn't receive new config updates from istiod
+
+Why 4: Why couldn't it receive config updates?
+→ Because the gRPC message exceeded the 4MB size limit
+
+Why 5: Why was the message over 4MB?
+→ Because we have 14,000 services and the default limit was never adjusted for our scale
+
+ROOT CAUSE: Infrastructure configuration not updated to match platform scale
+```
+
+## Example: Memory-Related 502 Errors
+
+```
+Problem: 2% of requests returned 502 during traffic spike
+
+Why 1: Why did requests return 502?
+→ Because the application pods were killed/restarted
+
+Why 2: Why were pods killed?
+→ Because they exceeded memory limits (OOMKilled)
+
+Why 3: Why did they exceed memory limits?
+→ Because traffic increased 150x (200 → 30k req/min) and memory usage scaled with connections
+
+Why 4: Why didn't we scale before hitting limits?
+→ Because HPA was based on CPU, not memory, and CPU didn't spike proportionally
+
+Why 5: Why wasn't memory included in scaling metrics?
+→ Because we hadn't profiled memory behavior under high-concurrency scenarios
+
+ROOT CAUSE: Autoscaling configuration not calibrated for memory-intensive traffic patterns
+```
+
+## Tips
+
+- **Don't stop at symptoms** - "The server crashed" is a symptom, not a cause
+- **Don't blame people** - "John didn't check" → "The checklist didn't include this verification"
+- **Multiple branches are OK** - Complex incidents often have multiple contributing root causes
+- **Actionable = root cause** - If you can write a TODO to fix it, you've found the root cause
+
+## Common Root Cause Categories
+
+| Category | Example Root Causes |
+|----------|-------------------|
+| **Configuration** | Defaults not adjusted for scale, missing limits |
+| **Monitoring** | No alert for this failure mode, wrong thresholds |
+| **Process** | No runbook, unclear ownership, missing checklist |
+| **Architecture** | Single point of failure, no circuit breaker |
+| **Testing** | Edge case not covered, no load testing |
+| **Documentation** | Outdated docs, tribal knowledge not written down |

package/.cursor/skills/incident-report/templates/client-report.md

@@ -0,0 +1,187 @@
+# Client-Facing Incident Report Template
+
+Use this template for customer communications. Adapt tone and detail level based on relationship and incident severity.
+
+---
+
+## Email Template (Standard)
+
+```markdown
+**Assunto:** [Status] Incidente de [Tipo] - [Nome do Site/Cliente]
+
+Prezado(a) [Nome],
+
+[Agradecemos por nos comunicar | Entramos em contato proativamente] sobre o incidente ocorrido em [data].
+
+**Resumo do que aconteceu:**
+
+[Explicação em 2-3 frases, sem jargão técnico. Foque no que o cliente experimentou, não nos detalhes internos.]
+
+**Impacto no seu site:**
+
+- [Impacto específico 1 - ex: "Aproximadamente X% das requisições retornaram erro"]
+- [Impacto específico 2 - ex: "O problema durou X minutos"]
+- [Se houve exposição de dados: detalhar exatamente o que foi exposto]
+
+**O que fizemos para resolver:**
+
+1. [Ação imediata tomada]
+2. [Verificação realizada]
+3. [Resultado: "Após essas ações, o problema foi resolvido e verificamos que..."]
+
+**O que estamos fazendo para evitar que isso aconteça novamente:**
+
+- [Medida preventiva 1 - seja específico]
+- [Medida preventiva 2]
+- [Medida preventiva 3 se aplicável]
+
+**Próximos passos:**
+
+[Se houver ações pendentes do lado deco ou do cliente]
+
+Permanecemos à disposição para quaisquer esclarecimentos adicionais.
+
+Atenciosamente,
+
+**[Nome]**  
+[Cargo], Deco.cx  
+[Email] | [WhatsApp se apropriado]
+```
+
+---
+
+## Email Template (Security/Data Exposure - Formal)
+
+```markdown
+**Assunto:** Comunicado de Segurança - Incidente em [Data]
+
+Prezado(a) [Nome],
+
+Entramos em contato para informá-lo(a) sobre um incidente de segurança que afetou [escopo].
+
+**O que aconteceu:**
+
+Em [data], identificamos [descrição não-técnica do problema]. [Duração do problema].
+
+**Quais dados foram potencialmente afetados:**
+
+- [Tipo de dado 1 - ex: "Conteúdo HTML das páginas"]
+- [Tipo de dado 2 - ex: "Dados de carrinho de compras"]
+- [Esclarecer o que NÃO foi afetado se relevante]
+
+**Impacto no seu ambiente:**
+
+[Descrição específica para este cliente]
+
+**Ações tomadas:**
+
+1. [Correção aplicada]
+2. [Verificação de segurança]
+3. [Limpeza de cache/dados se aplicável]
+
+**Medidas preventivas implementadas:**
+
+1. [Medida técnica 1]
+2. [Medida técnica 2]
+3. [Medida de monitoramento]
+
+**Recomendações para sua equipe:**
+
+- [Se houver ações recomendadas do lado do cliente]
+
+**Contatos para o comitê de investigação (se aplicável):**
+
+| Nome | Função | E-mail | WhatsApp |
+|------|--------|--------|----------|
+| [Nome] | [Cargo] | [email] | [telefone] |
+
+Lamentamos profundamente qualquer inconveniente causado e reafirmamos nosso compromisso com a segurança dos dados de nossos clientes.
+
+Atenciosamente,
+
+**[Nome do Executivo/Co-fundador]**  
+[Cargo], Deco.cx
+```
+
+---
+
+## Email Template (Performance Degradation)
+
+```markdown
+**Assunto:** Relatório de Incidente - Degradação de Performance em [Data]
+
+Prezado(a) [Nome],
+
+Gostaríamos de compartilhar detalhes sobre o incidente de performance que afetou [site/serviço] em [data].
+
+**O que aconteceu:**
+
+Durante [período], observamos [descrição do problema - ex: "um aumento significativo no tempo de resposta" ou "erros intermitentes 502"].
+
+**Números do impacto:**
+
+- Período afetado: [horário início] às [horário fim]
+- Taxa de erro: [X% das requisições]
+- Tempo médio de resposta: [se aplicável]
+
+**Causa identificada:**
+
+[Explicação simplificada - ex: "Um aumento inesperado de tráfego excedeu a capacidade de memória alocada para o serviço"]
+
+**Ações tomadas:**
+
+1. [Ação de mitigação]
+2. [Ajuste de capacidade]
+3. [Monitoramento intensificado]
+
+**Melhorias implementadas:**
+
+- [Ajuste de infraestrutura]
+- [Novo alerta configurado]
+- [Processo atualizado]
+
+Continuamos monitorando ativamente e estamos à disposição para qualquer esclarecimento.
+
+Atenciosamente,
+
+**[Nome]**  
+[Cargo], Deco.cx
+```
+
+---
+
+## Writing Guidelines for Client Reports
+
+### DO
+
+- Start with the current status (resolved/ongoing)
+- Acknowledge the impact on their business
+- Be specific about what happened and what was done
+- Provide concrete prevention measures
+- Include contact information for follow-up
+- Use "we" language (we identified, we fixed)
+
+### DON'T
+
+- Use technical jargon without explanation
+- Be defensive or make excuses
+- Blame third parties (even if true)
+- Minimize the impact
+- Make promises you can't keep
+- Share internal details that don't help the customer
+
+### Tone Calibration
+
+| Severity | Tone | Signer |
+|----------|------|--------|
+| P0 Critical | Formal, executive-level | Co-founder/CEO |
+| P1 High | Professional, detailed | Engineering Lead |
+| P2 Medium | Professional, concise | Support/Account Manager |
+| P3 Low | Friendly, informative | Support Team |
+
+### Translation Notes (PT-BR)
+
+- "Incidente" not "problema" or "bug"
+- "Identificamos" not "descobrimos"
+- "Implementamos medidas" not "consertamos"
+- "Lamentamos o inconveniente" (use sparingly, once per email)

package/.cursor/skills/incident-report/templates/internal-report.md

@@ -0,0 +1,206 @@
+# Internal Incident Report Template
+
+Copy and fill in this template for technical post-mortems.
+
+---
+
+```markdown
+# Incident: [Brief Descriptive Title]
+
+**Date of incident:** YYYY-MM-DD  
+**Severity:** [P0 Critical | P1 High | P2 Medium | P3 Low]  
+**Type:** [Outage | Security | Data Leak | Performance | Configuration]  
+**Affected systems:** [List systems, clusters, services]  
+**Root cause:** [One-line summary]  
+**Impact:** [One-line impact summary]
+
+---
+
+## TL;DR - Critical Information
+
+### What Happened
+1. [First key point]
+2. [Second key point]
+3. [Third key point]
+
+### Immediate Fix Applied
+```code
+[The fix that resolved the issue]
+```
+
+### Why This Matters
+- [Business/security implication 1]
+- [Business/security implication 2]
+
+---
+
+## Executive Summary
+
+[One paragraph (3-5 sentences) explaining what happened, what caused it, what was the impact, and how it was resolved. Written for someone who will only read this section.]
+
+---
+
+## Timeline
+
+All times in UTC-3 (São Paulo).
+
+| Time | Event |
+|------|-------|
+| HH:MM | [Detection: How was the issue detected?] |
+| HH:MM | [Investigation: First investigative action] |
+| HH:MM | [Escalation: Who was brought in?] |
+| HH:MM | [Identification: Root cause identified] |
+| HH:MM | [Mitigation: Temporary fix applied] |
+| HH:MM | [Resolution: Permanent fix deployed] |
+| HH:MM | [Verification: Confirmed resolution] |
+
+**Total duration:** X hours Y minutes  
+**Time to detection:** X minutes  
+**Time to resolution:** X hours Y minutes
+
+---
+
+## Root Cause Analysis
+
+### The Problem
+
+[Detailed technical explanation of what went wrong. Include architecture context if needed.]
+
+### Why It Happened
+
+[Use 5-Whys or similar technique]
+
+1. **Why** did [symptom]? → Because [cause 1]
+2. **Why** did [cause 1]? → Because [cause 2]
+3. **Why** did [cause 2]? → Because [cause 3]
+4. **Why** did [cause 3]? → Because [root cause]
+
+### Contributing Factors
+
+- [Factor 1 - e.g., missing monitoring]
+- [Factor 2 - e.g., configuration drift]
+- [Factor 3 - e.g., insufficient testing]
+
+---
+
+## Impact Assessment
+
+### Quantified Impact
+
+| Metric | Value |
+|--------|-------|
+| Duration | X hours |
+| Affected requests | X / Y total (Z%) |
+| Error rate | X% |
+| Affected customers | X sites |
+| Revenue impact | [If applicable] |
+
+### Affected Customers
+
+[List specific customers if known, or describe the affected segment]
+
+### Data Exposure (if applicable)
+
+- **Data types exposed:** [List specific data types]
+- **Exposure scope:** [Who could see what]
+- **Duration of exposure:** [Time window]
+
+---
+
+## Resolution
+
+### Immediate Fix
+
+[What was done to stop the bleeding]
+
+```yaml
+# Configuration change, command, or code
+[Actual fix applied]
+```
+
+### Verification Steps
+
+```bash
+# Commands used to verify the fix
+[Verification commands]
+```
+
+### Rollback Plan (if applicable)
+
+[How to undo the fix if it causes issues]
+
+---
+
+## Action Items
+
+### Priority 1: Critical (This Week)
+
+| Action | Owner | Status | Due |
+|--------|-------|--------|-----|
+| [Action 1] | @name | TODO | YYYY-MM-DD |
+| [Action 2] | @name | TODO | YYYY-MM-DD |
+
+### Priority 2: High (This Sprint)
+
+| Action | Owner | Status | Due |
+|--------|-------|--------|-----|
+| [Action 3] | @name | TODO | YYYY-MM-DD |
+
+### Priority 3: Medium (This Quarter)
+
+| Action | Owner | Status | Due |
+|--------|-------|--------|-----|
+| [Action 4] | @name | TODO | YYYY-MM-DD |
+
+---
+
+## Lessons Learned
+
+### What Went Well
+- [Positive 1 - e.g., quick detection]
+- [Positive 2 - e.g., effective communication]
+
+### What Could Be Improved
+- [Improvement 1]
+- [Improvement 2]
+
+### Process Gaps Identified
+- [Gap 1 - e.g., no runbook existed]
+- [Gap 2 - e.g., monitoring blind spot]
+
+---
+
+## Monitoring & Alerting
+
+### Existing Alerts (that fired or should have)
+
+| Alert | Status | Notes |
+|-------|--------|-------|
+| [Alert name] | [Fired/Did not fire] | [Why] |
+
+### New Alerts Needed
+
+```yaml
+# Prometheus/Grafana alert definition
+[Alert configuration]
+```
+
+---
+
+## References
+
+- **Slack thread:** [link]
+- **Related PRs:** [links]
+- **Logs:** [link to log explorer query]
+- **Dashboard:** [link to relevant dashboard]
+- **Related incidents:** [links to similar past incidents]
+
+---
+
+## Document History
+
+| Date | Author | Changes |
+|------|--------|---------|
+| YYYY-MM-DD | [Name] | Initial draft |
+| YYYY-MM-DD | [Name] | Added [section] |
+```

package/.cursor/skills/template-skill/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: template-skill
+description: A template skill to use as a starting point for new skills. Copy this folder and customize.
+---
+
+# Template Skill
+
+This is a template for creating new Agent Skills.
+
+## When to Use This Skill
+
+Describe when Claude should activate this skill.
+
+## Quick Start
+
+1. Step one
+2. Step two
+3. Step three
+
+## Files in This Skill
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | This overview |
+| Add more files as needed... |
+
+## Examples
+
+Add examples of how to use this skill.
+
+## Guidelines
+
+- Guideline 1
+- Guideline 2
+
+## Related Resources
+
+- Link to related docs or resources

package/.github/workflows/release.yml

@@ -0,0 +1,32 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  packages: write
+  issues: write
+  pull-requests: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+
+      - run: npm install
+
+      - name: Release
+        run: npx semantic-release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}