izanagi-ai 2.0.0

package/skills/sre-reliability/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: sre-reliability
+description: |
+  Skill de Site Reliability Engineering (SRE) para o Portal. Aborda SLIs/SLOs/SLAs,
+  error budgets, observabilidade, incident response, capacity planning e reliability patterns.
+  Use esta skill para garantir confiabilidade e disponibilidade do sistema.
+---
+
+# Skill SRE & Reliability — Portal
+
+## SRE Fundamentals
+
+### SLIs (Service Level Indicators)
+| Indicador | Metrica |
+|-----------|---------|
+| Availability | `(successful_requests / total_requests) * 100` |
+| Latency | `p50, p95, p99` response time |
+| Throughput | Requests per second |
+| Error Rate | `(5xx / total) * 100` |
+| Saturation | CPU/Memory/Disk usage % |
+
+### SLOs (Service Level Objectives)
+```
+Latency: 99% of requests < 500ms (p99 rolling 30d)
+Availability: 99.9% uptime (monthly)
+Error Rate: < 0.1% 5xx errors
+```
+
+### SLAs (Service Level Agreements)
+- **99.9%** = 8.77h downtime/year (aceitavel)
+- **99.99%** = 52.56m downtime/year (recomendado)
+- **99.999%** = 5.26m downtime/year (critico)
+
+---
+
+## Error Budget
+
+```
+Error Budget = 100% - SLO
+ex: SLO 99.9% → Error Budget = 0.1% = ~43min/month
+```
+
+- **Disponivel**: tempo que o sistema pode falhar sem violar SLO
+- **Uso**: deploys so sao permitidos se error budget ainda disponivel
+- **Se esgotar**: congelamento de deploys ate recuperar
+
+---
+
+## Observabilidade
+
+### Three Pillars
+```
+Logs (events) + Metrics (aggregations) + Traces (distributed)
+```
+
+### Stack Recomendada
+| Ferramenta | Uso |
+|------------|-----|
+| Grafana + Prometheus | Metrics + dashboards |
+| Sentry | Error tracking |
+| OpenTelemetry | Distributed tracing |
+| Vercel Analytics | Core Web Vitals |
+| CloudWatch | AWS metrics + logs |
+| PagerDuty / OpsGenie | On-call alerting |
+
+---
+
+## Incident Response
+
+### Severity Levels
+| Severity | Exemplo | SLA Response |
+|----------|---------|-------------|
+| SEV-1 | Site down | 15min |
+| SEV-2 | Feature broken | 1h |
+| SEV-3 | Bug menor | 8h |
+| SEV-4 | Cosmetico | Next sprint |
+
+### Response Process
+1. **Detect**: alerta (PagerDuty) ou report de usuario
+2. **Triage**: determinar severidade, notificar equipe
+3. **Mitigate**: rollback, feature flag, scale up
+4. **Resolve**: aplicar fix permanente
+5. **Learn**: postmortem (blameless), acoes preventivas
+
+---
+
+## Reliability Patterns
+
+| Pattern | Descricao |
+|---------|-----------|
+| Circuit Breaker | Parar chamadas a servico falho, retry apos timeout |
+| Bulkhead | Isolar recursos por servico (thread pools separados) |
+| Retry with Backoff | Exponential backoff + jitter |
+| Timeout | Sempre configurar timeouts em chamadas externas |
+| Rate Limiting | Proteger contra abuso e picos de trafego |
+| Graceful Degradation | Funcionalidades nao-criticas falham sem quebrar o core |
+| Health Checks | Endpoint `/health` para readiness/liveness |
+
+---
+
+## Capacity Planning
+
+```yaml
+# Metrica de crescimento
+requests_per_month: 1_000_000
+growth_rate: 20%  # anual
+projected: 1_200_000  # proximo ano
+```
+
+### Passos
+1. Monitorar trafego atual + tendencias
+2. Identificar bottlenecks (DB, API, compute)
+3. Calcular capacidade necessaria (com buffer de 50%)
+4. Auto-scaling configurado (min/max/desired)
+5. Load test periodicos para validar

package/skills/staff-engineer.md

@@ -0,0 +1,61 @@
+# Skill: Staff Engineer
+
+> Version 1.0.0 | Priority: High
+> Dependencies: Senior Code Reviewer, Tech Lead
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+Staff Engineer operates at the team/cluster level. Deep technical expertise in one or more domains, leads complex technical projects, designs large features, and unblocks other engineers.
+
+---
+
+## Responsibilities
+
+```yaml
+execution:
+  - Own delivery of large, multi-sprint features
+  - Break down complex projects into manageable pieces
+  - Write critical or high-risk code personally
+
+design:
+  - Lead technical design for major features
+  - Review and approve designs from senior engineers
+  - Identify technical risks early
+
+mentorship:
+  - Mentor senior engineers (tech lead pipeline)
+  - Run code review sessions (not just individual reviews)
+  - On-call escalation point for production issues
+
+quality:
+  - Set testing standards for the team
+  - Drive performance improvements
+  - Own CI/CD pipeline quality
+```
+
+---
+
+## Staff vs Principal
+
+```yaml
+Staff:
+  scope: "Team or cluster (2-4 teams)"
+  horizon: "3-6 months"
+  focus: "Deep technical excellence"
+  output: "Working systems, mentored engineers"
+
+Principal:
+  scope: "Entire organization"
+  horizon: "6-12 months"
+  focus: "Technical strategy, org-wide quality"
+  output: "Technical vision, organizational change"
+```
+
+---
+
+## Changelog
+
+### 1.0.0 — Initial release. Responsibilities, staff vs principal comparison.

package/skills/task-planner.md

@@ -0,0 +1,61 @@
+# Skill: Task Planner
+
+> Version 1.0.0 | Priority: High
+> Dependencies: Planning Engine, Project Manager
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+Task Planner breaks work into manageable, assignable tasks. Each task is atomic (1 person, < 1 day), has clear acceptance criteria, and is ordered by dependencies.
+
+---
+
+## Task Breakdown
+
+```yaml
+epic: "Payment integration"
+  task_1: "Create payments migration"
+    effort: 2h
+    deps: []
+    acceptance: "payments table exists with correct schema"
+    
+  task_2: "Create Payment model"
+    effort: 1h
+    deps: [task_1]
+    acceptance: "Payment model with relationships and casts"
+    
+  task_3: "Create StripeService"
+    effort: 4h
+    deps: []
+    acceptance: "Can create, retrieve, refund payments via Stripe"
+    
+  task_4: "Create PaymentController"
+    effort: 3h
+    deps: [task_2, task_3]
+    acceptance: "POST /api/payments creates payment, returns 201"
+    
+  task_5: "Write payment tests"
+    effort: 3h
+    deps: [task_4]
+    acceptance: "Unit + feature tests cover happy path and errors"
+```
+
+---
+
+## Estimation Guidelines
+
+```
+1 point = 2-4 hours (simple, well-understood)
+2 points = 1 day (moderate complexity)
+3 points = 2 days (complex, some unknowns)
+5 points = 1 week (very complex, many unknowns)
+8+ points = must break down further
+```
+
+---
+
+## Changelog
+
+### 1.0.0 — Initial release. Breakdown, estimation, acceptance criteria.

package/skills/tech-lead.md

@@ -0,0 +1,59 @@
+# Skill: Tech Lead
+
+> Version 1.0.0 | Priority: High
+> Dependencies: Software Architect, Senior Code Reviewer
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+Tech Lead bridges engineering and product. Leads a single team, ensures technical quality, unblocks engineers, translates product requirements into technical tasks, and maintains team health.
+
+---
+
+## Responsibilities
+
+```yaml
+technical:
+  - Set technical direction for the team
+  - Review all significant PRs
+  - Ensure code quality and test coverage
+  - Manage technical debt (track, prioritize, reduce)
+
+people:
+  - Unblock engineers daily
+  - Run standups and retros
+  - Conduct 1:1s
+  - Identify skill gaps and training needs
+
+product:
+  - Translate product requirements into technical specs
+  - Estimate effort and flag risks
+  - Communicate technical constraints to product manager
+
+process:
+  - Enforce team conventions (coding, git, review)
+  - Triage and prioritize bugs
+  - Onboard new team members
+```
+
+---
+
+## Daily Rhythm
+
+```
+09:00 — Standup (blockers, priorities)
+09:30 — Deep work (design, code, review)
+11:30 — 1:1 with team members or product
+13:00 — Code reviews (batch)
+14:00 — Unblocking, design discussions
+16:00 — Sprint planning prep, metrics review
+17:00 — Documentation, ADRs, process improvements
+```
+
+---
+
+## Changelog
+
+### 1.0.0 — Initial release. Responsibilities, daily rhythm.

package/skills/technical-debt-analyzer.md

@@ -0,0 +1,81 @@
+# Skill: Technical Debt Analyzer
+
+> Version 1.0.0 | Priority: High
+> Dependencies: Complexity Analyzer, Clean Code Validator
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+Technical Debt Analyzer identifies, quantifies, and prioritizes technical debt. Measures debt as "time to fix" vs "time to implement correctly." Produces a prioritized backlog for debt reduction.
+
+---
+
+## Debt Categories
+
+| Category | Examples | Interest Rate |
+|----------|---------|---------------|
+| **Code** | Dead code, duplication, complex functions | High — affects every change |
+| **Design** | Missing abstractions, god classes, circular dependencies | High — makes changes hard |
+| **Test** | Missing tests, flaky tests, slow tests | Medium — reduces confidence |
+| **Documentation** | Missing docs, outdated docs, no ADRs | Low — slows onboarding |
+| **Infrastructure** | Manual deploys, no monitoring, old deps | High — blocks velocity |
+| **Security** | Known vulnerabilities, missing auth | Critical — risk of breach |
+
+---
+
+## Debt Estimation
+
+```yaml
+finding:
+  description: "OrderService has 47-line calculateTotals method"
+  
+  cost_to_fix_now:
+    analysis: 0.5h
+    refactor: 2h
+    tests: 1h
+    review: 0.5h
+    total: 4h
+    
+  cost_to_fix_later:
+    find_and_understand: 2h (harder to navigate)
+    refactor: 3h (more dependencies added)
+    tests: 2h (less familiarity)
+    review: 1h
+    total: 8h
+    
+  interest_rate: "2x every 6 months"
+  priority: "high"
+```
+
+---
+
+## Debt Backlog
+
+```yaml
+prioritized_debt:
+  - priority: 1
+    item: "Remove duplicated payment logic in 3 controllers"
+    effort: 3h
+    impact: "Eliminates inconsistent behavior"
+    
+  - priority: 2
+    item: "Add PHPStan level max"
+    effort: 8h
+    impact: "Prevents entire class of bugs"
+    
+  - priority: 3
+    item: "Extract OrderService (47 lines → 3 methods)"
+    effort: 4h
+    impact: "Makes future order changes safer"
+  
+  total_effort: 40h
+  estimated_sprint_impact: "2 sprints to clear high-priority items"
+```
+
+---
+
+## Changelog
+
+### 1.0.0 — Initial release. Categories, estimation, prioritized backlog.

package/skills/technical-writer.md

@@ -0,0 +1,39 @@
+# Skill: Technical Writer
+
+> Version 1.0.0 | Priority: Medium
+> Dependencies: Documentation Writer
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+Technical Writer produces clear, concise technical documentation for developers and end-users. Follows the Diátaxis framework: tutorials, how-to guides, reference, and explanation.
+
+---
+
+## Diátaxis Framework
+
+```yaml
+tutorials: "Learning-oriented — guide a beginner through a complete task"
+how_to: "Task-oriented — solve a specific problem"
+reference: "Information-oriented — describe the system (API, config)"
+explanation: "Understanding-oriented — explain concepts and reasoning"
+```
+
+## Writing Principles
+
+```
+- One idea per paragraph
+- Short sentences (max 25 words)
+- Active voice ("Click Submit" not "The Submit button should be clicked")
+- Code examples before explanation
+- Consistent terminology
+- No assumptions about reader knowledge (link to prerequisites)
+```
+
+---
+
+## Changelog
+
+### 1.0.0 — Initial release. Diátaxis, writing principles.

package/skills/tradeoff-analyzer.md

@@ -0,0 +1,79 @@
+# Skill: Trade-off Analyzer
+
+> Version 1.0.0 | Priority: Medium
+> Dependencies: Software Architect
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+Trade-off Analyzer evaluates multiple approaches against defined criteria. Produces a structured comparison to help make informed decisions.
+
+---
+
+## Comparison Criteria
+
+```yaml
+criteria:
+  complexity:
+    description: "How complex is the implementation?"
+    weight: 3
+    
+  maintainability:
+    description: "How easy to maintain over time?"
+    weight: 4
+    
+  performance:
+    description: "How fast is it?"
+    weight: 3
+    
+  scalability:
+    description: "How well does it scale?"
+    weight: 2
+    
+  cost:
+    description: "Development + operational cost"
+    weight: 2
+    
+  risk:
+    description: "Probability of issues"
+    weight: 4
+```
+
+---
+
+## Example Comparison
+
+```yaml
+decision: "Should we use REST or GraphQL for the API?"
+
+options:
+  - name: "REST"
+    scores:
+      complexity: 5 (simple, well-known pattern)
+      maintainability: 4 (clear endpoints)
+      performance: 4 (caching, pagination)
+      scalability: 3 (multiple requests)
+      cost: 5 (no new tools)
+      risk: 5 (proven, well-understood)
+    weighted_total: 4.4
+  
+  - name: "GraphQL"
+    scores:
+      complexity: 2 (new patterns, resolvers, N+1 risk)
+      maintainability: 3 (flexible but complex)
+      performance: 3 (batching, dataloader needed)
+      scalability: 4 (single endpoint, precise queries)
+      cost: 3 (new tools: Apollo/graphql-php)
+      risk: 3 (N+1, no HTTP caching)
+    weighted_total: 3.1
+
+recommendation: "Use REST for the public API. Consider GraphQL for internal admin dashboard."
+```
+
+---
+
+## Changelog
+
+### 1.0.0 — Initial release. Criteria, scoring, example.

package/skills/uml-generator.md

@@ -0,0 +1,72 @@
+# Skill: UML Generator
+
+> Version 1.0.0 | Priority: Low
+> Dependencies: Software Architect
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+UML Generator produces UML diagrams from architecture descriptions. Generates PlantUML or Mermaid.js code for class diagrams, use case diagrams, and component diagrams.
+
+---
+
+## Diagram Types
+
+```yaml
+class_diagram: entities, attributes, methods, relationships
+component_diagram: services, controllers, repositories, data flow
+use_case: actors, use cases, system boundary
+sequence: object interactions, message flow over time
+```
+
+---
+
+## PlantUML Example
+
+```plantuml
+@startuml
+class User {
+  - id: UUID
+  - name: string
+  - email: string
+  + create(data): User
+  + update(data): User
+}
+
+class Post {
+  - id: UUID
+  - title: string
+  - content: string
+  + publish(): void
+}
+
+User "1" --> "*" Post : creates
+@enduml
+```
+
+## Mermaid Example
+
+```mermaid
+classDiagram
+    class User {
+        -UUID id
+        -string name
+        -string email
+        +create(data) User
+    }
+    class Post {
+        -UUID id
+        -string title
+        -string content
+        +publish() void
+    }
+    User "1" --> "*" Post : creates
+```
+
+---
+
+## Changelog
+
+### 1.0.0 — Initial release. Types, PlantUML, Mermaid.

package/skills/ux-reviewer.md

@@ -0,0 +1,61 @@
+# Skill: UX Reviewer
+
+> Version 1.0.0 | Priority: Medium
+> Dependencies: Frontend Engineer
+> Compatibility: ">=1.0.0"
+
+---
+
+## Identity
+
+UX Reviewer evaluates user interfaces against usability heuristics: consistency, feedback, error prevention, user control, and accessibility.
+
+---
+
+## Nielsen's Heuristics
+
+```yaml
+1_visibility: "System status visible (loading indicators, progress bars)"
+2_real_world: "Use user's language, not technical jargon"
+3_control: "Undo/redo, cancel, easy navigation back"
+4_consistency: "Same patterns throughout (buttons, forms, icons)"
+5_error_prevention: "Confirm destructive actions, validate inline"
+6_recognition: "Show options rather than ask to remember"
+7_flexibility: "Shortcuts for power users, simple paths for beginners"
+8_aesthetic: "Clean design, whitespace, visual hierarchy"
+9_errors: "Clear error messages with recovery path"
+10_help: "Contextual help, documentation accessible"
+```
+
+---
+
+## UX Report
+
+```yaml
+ux_review:
+  page: "Checkout page"
+  
+  findings:
+    - heuristic: "1_visibility"
+      issue: "No loading state when processing payment"
+      severity: "high"
+      fix: "Add spinner + 'Processing payment...' message"
+    
+    - heuristic: "5_error_prevention"
+      issue: "No confirmation before cancelling order"
+      severity: "medium"
+      fix: "Add 'Are you sure?' modal"
+    
+    - heuristic: "9_errors"
+      issue: "Generic 'Something went wrong' message"
+      severity: "high"
+      fix: "Specific messages: 'Card declined', 'Insufficient funds'"
+    
+  score: 7 / 10
+```
+
+---
+
+## Changelog
+
+### 1.0.0 — Initial release. Heuristics, report format.