claude-code-arcane 1.0.0

package/skills/roadmap-communicator/scripts/changelog_generator.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+"""Generate changelog sections from git log or piped commit messages using conventional commit prefixes."""
+
+import argparse
+import shutil
+import subprocess
+import sys
+from collections import defaultdict
+
+
+SECTIONS = {
+    "feat": "Features",
+    "fix": "Fixes",
+    "docs": "Documentation",
+    "refactor": "Refactors",
+    "test": "Tests",
+    "chore": "Chores",
+    "perf": "Performance",
+    "ci": "CI",
+    "build": "Build",
+    "style": "Style",
+    "revert": "Reverts",
+}
+
+DEMO_COMMITS = [
+    "feat: add user dashboard with analytics widgets",
+    "feat: implement dark mode toggle",
+    "fix: resolve crash on empty CSV import",
+    "fix: correct timezone offset in calendar view",
+    "docs: update API reference for v2 endpoints",
+    "refactor: extract shared validation into utils module",
+    "chore: bump dependencies to latest patch versions",
+    "perf: optimize database queries for user listing",
+]
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Generate changelog from git commits or piped input.",
+        epilog="Examples:\n"
+               "  %(prog)s --from v1.0.0 --to HEAD\n"
+               "  git log --pretty=format:%%s v1.0..HEAD | %(prog)s --stdin\n"
+               "  %(prog)s --demo\n",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--from", dest="from_ref", default="HEAD~50",
+                        help="Start ref for git log (default: HEAD~50)")
+    parser.add_argument("--to", dest="to_ref", default="HEAD",
+                        help="End ref for git log (default: HEAD)")
+    parser.add_argument("--format", choices=["markdown", "text"], default="markdown",
+                        help="Output format (default: markdown)")
+    parser.add_argument("--stdin", action="store_true",
+                        help="Read commit subjects from stdin instead of git log")
+    parser.add_argument("--demo", action="store_true",
+                        help="Run with sample data (no git required)")
+    return parser.parse_args()
+
+
+def get_git_log(from_ref: str, to_ref: str) -> list[str]:
+    """Get commit subjects from git log. Requires git on PATH and a git repo."""
+    if not shutil.which("git"):
+        print("Error: git not found on PATH. Use --stdin or --demo instead.", file=sys.stderr)
+        sys.exit(1)
+    commit_range = f"{from_ref}..{to_ref}"
+    cmd = ["git", "log", "--pretty=format:%s", commit_range]
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=30)
+    except subprocess.TimeoutExpired:
+        print("Error: git log timed out.", file=sys.stderr)
+        sys.exit(1)
+    if result.returncode != 0:
+        print(f"Error: git log failed: {result.stderr.strip()}", file=sys.stderr)
+        sys.exit(1)
+    lines = [line.strip() for line in result.stdout.splitlines() if line.strip()]
+    return lines
+
+
+def read_stdin() -> list[str]:
+    """Read commit subjects from stdin, one per line."""
+    return [line.strip() for line in sys.stdin if line.strip()]
+
+
+def group_commits(subjects: list[str]) -> dict[str, list[str]]:
+    grouped: dict[str, list[str]] = defaultdict(list)
+
+    for subject in subjects:
+        commit_type = "other"
+        for prefix in SECTIONS:
+            if subject.startswith(f"{prefix}:") or subject.startswith(f"{prefix}("):
+                commit_type = prefix
+                break
+        grouped[commit_type].append(subject)
+
+    return grouped
+
+
+def render_markdown(grouped: dict[str, list[str]]) -> str:
+    out = ["# Changelog", ""]
+    ordered_types = list(SECTIONS.keys()) + ["other"]
+    for commit_type in ordered_types:
+        commits = grouped.get(commit_type, [])
+        if not commits:
+            continue
+        header = SECTIONS.get(commit_type, "Other")
+        out.append(f"## {header}")
+        for item in commits:
+            out.append(f"- {item}")
+        out.append("")
+    return "\n".join(out).rstrip() + "\n"
+
+
+def render_text(grouped: dict[str, list[str]]) -> str:
+    out: list[str] = []
+    ordered_types = list(SECTIONS.keys()) + ["other"]
+    for commit_type in ordered_types:
+        commits = grouped.get(commit_type, [])
+        if not commits:
+            continue
+        header = SECTIONS.get(commit_type, "Other")
+        out.append(header.upper())
+        for item in commits:
+            out.append(f"* {item}")
+        out.append("")
+    return "\n".join(out).rstrip() + "\n"
+
+
+def main() -> int:
+    args = parse_args()
+
+    if args.demo:
+        subjects = DEMO_COMMITS
+    elif args.stdin:
+        subjects = read_stdin()
+    else:
+        subjects = get_git_log(args.from_ref, args.to_ref)
+
+    if not subjects:
+        print("No commits found.", file=sys.stderr)
+        return 0
+
+    grouped = group_commits(subjects)
+
+    if args.format == "markdown":
+        print(render_markdown(grouped), end="")
+    else:
+        print(render_text(grouped), end="")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/rollback-strategy/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: rollback-strategy
+description: "Rollback strategy: todo deploy reversible en <5min. Code/config/data/infra, canary, auto-rollback, Cloud Run, GKE, mobile."
+category: "operations"
+argument-hint: "[code|config|data|infra]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+---
+# Rollback Strategy
+
+> **Todo deploy debe ser reversible en <5 minutos. Si no lo es, es un deploy peligroso.**
+
+## Cuándo usar / NO usar
+
+| Usar | NO usar |
+|------|---------|
+| Planificar rollback **antes** de deployar | Fix forward simple (typo, log) — a veces hotfix más rápido |
+| Incidente en producción | Datos corruptos ya escritos — rollback código no arregla datos |
+| Diseñar CI/CD pipelines | Post-compatibility window con schema irreversible |
+| Validar camino de reversa en breaking changes | Estáticos en CDN — purgar + redeploy puede ser más directo |
+| DR drills trimestrales | |
+
+Cada release necesita: comando concreto de rollback escrito antes, responsable que lo ejecuta, criterio claro de cuándo (SLO, error rate), prueba de que funciona.
+
+## Tipos de rollback
+
+| Tipo | Qué | Dificultad |
+|------|-----|------------|
+| **Code** | Redeploy imagen Docker versión anterior | Simple si versioning correcto |
+| **Config** | Revertir feature flag o env var — instantáneo sin redeploy | Preferir siempre |
+| **Data** | Revertir migración DB — `DROP COLUMN` no vuelve sin restore | Difícil/imposible. Ver `/data-migrations` |
+| **Infra** | `terraform apply` versión anterior del state | Requiere state limpio, revisar drift |
+
+## Estrategia por layer
+
+### Stateless (Cloud Run, GKE)
+Rollback = redeploy imagen anterior. GKE: `kubectl rollout undo`. Cloud Run: cambiar tráfico a revision previa con `gcloud run services update-traffic`.
+
+### DB migrations — expand/contract
+Nunca drops irreversibles en misma release que código. 4 fases: expand (agregar nuevo backward-compatible) → migrate data + dual-write → cutover (leer de nuevo) → contract (drop viejo una release después). Ver `/data-migrations`.
+
+### Feature flags
+Toggle off instantáneo sin redeploy. Regla: toda feature user-facing va detrás de flag con kill switch server-side.
+
+## Versioning de artefactos
+
+- Tag por **git SHA**: `gcr.io/educabot/service:$GIT_SHA`. NUNCA `:latest` en prod
+- Retener mínimo **10 imágenes** (lifecycle policy Artifact Registry)
+- Mapear SHA ↔ release ↔ ticket Jira (auditoría)
+
+## DB compatibility window
+
+Código N-1 debe funcionar con schema N, y código N con schema N-1, por al menos una release. Nunca mergear breaking schema + código en mismo PR. Separar: PR1=expand, PR2=código, PR3=contract.
+
+## Runbook rollback manual
+
+> → Read references/runbook-commands.md for exact rollback commands (Cloud Run, GKE, feature flags, GitHub Actions, post-rollback, PITR, cache/CDN)
+
+## References
+
+> → Read references/canary-auto-rollback.md for canary progression and auto-rollback triggers
+> → Read references/anti-patterns.md for common rollback anti-patterns
+> → Read references/pre-deploy-checklist.md for the pre-deploy validation checklist
+> → Read references/mobile-rollback.md for React Native rollback mitigations
+> → Read references/communication-protocol.md for incident communication protocol
+
+## Post-rollback
+
+1. Crear incident con `/incident`
+2. Capturar logs del período malo antes de rotación (ver runbook)
+3. Capturar métricas (Grafana/Cloud Monitoring)
+4. RCA (5 whys, fishbone)
+5. Fix forward: arreglar, testear, redeployar — no quedar en versión vieja indefinidamente
+
+## Delegación
+
+- `/data-migrations` — expand/contract, migraciones reversibles
+- `/deploy-check` — checklist pre-deploy completa
+- `/incident` — post-mortem + ticket Jira
+- `/audit-dev` — auditar pipelines y runbooks

package/skills/rollback-strategy/references/anti-patterns.md

@@ -0,0 +1,14 @@
+# Anti-patterns de Rollback
+
+- `:latest` en prod — rollback imposible
+- Schema breaking + codigo breaking en misma release
+- Nunca probar rollback — descubris que no funciona cuando lo necesitas
+- DB restore sin drill previo
+- Rollback sin post-mortem
+- "Deshacer merge en git" sin plan real de redeploy
+- Flag sin kill switch server-side
+- Sin runbook — nadie sabe comandos a las 3am
+- Sin invalidar cache/CDN
+- No retener imagenes viejas (10 minimo)
+- Rollback workflow sin approval gate
+- Ignorar mobile en la estrategia

package/skills/rollback-strategy/references/canary-auto-rollback.md

@@ -0,0 +1,17 @@
+# Canary + Auto-rollback
+
+## Canary Progression
+
+5% -> 25% -> 50% -> 100% con pausas y checks entre cada paso.
+
+## Auto-rollback Triggers
+
+- SLO burn rate >2x en 10min
+- Error rate 5xx >baseline+3sigma por 3min
+- p95 latency >umbral definido
+- Health check failures >20% replicas
+
+## Herramientas
+
+- **GKE:** Argo Rollouts, Flagger
+- **Cloud Run:** Cloud Deploy

package/skills/rollback-strategy/references/communication-protocol.md

@@ -0,0 +1,6 @@
+# Comunicacion durante Rollback
+
+- Status page update (Statuspage / Instatus)
+- Slack #incidents: que, cuando, impacto, ETA, responsable
+- Email stakeholders si user-facing
+- Horario escolar LatAm: escalada inmediata

package/skills/rollback-strategy/references/mobile-rollback.md

@@ -0,0 +1,10 @@
+# Mobile Rollback (React Native)
+
+No hay rollback instantaneo por App Store review.
+
+## Mitigaciones
+
+- **Feature flags server-driven** — toggle sin release
+- **OTA updates** (Expo Updates / CodePush) para JS bundle
+- **Version minima forzada** (force update) — obligar update si version rota
+- **Compatibilidad API con N-2 versiones** — nunca romper clientes viejos

package/skills/rollback-strategy/references/pre-deploy-checklist.md

@@ -0,0 +1,15 @@
+# Checklist Pre-deploy
+
+- [ ] Artefacto taggeado por `$GIT_SHA`
+- [ ] 10+ imagenes retenidas en Artifact Registry
+- [ ] Schema expand/contract separados de codigo
+- [ ] Compatibility window N-1 validada
+- [ ] Comando rollback escrito en ticket/PR
+- [ ] Feature flag con kill switch si user-facing
+- [ ] Canary configurado para cambios riesgosos
+- [ ] Auto-rollback triggers definidos
+- [ ] Workflow rollback.yml disponible y probado
+- [ ] Runbook actualizado con comandos del servicio
+- [ ] DR drill DB restore ejecutado ultimo trimestre
+- [ ] Responsable on-call identificado
+- [ ] Plan comunicacion listo

package/skills/rollback-strategy/references/runbook-commands.md

@@ -0,0 +1,147 @@
+# Runbook — Comandos de Rollback
+
+## Cloud Run
+
+```bash
+# 1. Listar revisions disponibles
+gcloud run revisions list --service=<service-name> --region=<region> \
+  --format="table(name,status.observedGeneration,spec.containerConcurrency)"
+
+# 2. Ver tráfico actual
+gcloud run services describe <service-name> --region=<region> \
+  --format="value(status.traffic)"
+
+# 3. Rollback a revision anterior (redirigir 100% del tráfico)
+gcloud run services update-traffic <service-name> \
+  --region=<region> \
+  --to-revisions=<revision-name>=100
+
+# 4. Verificar
+gcloud run services describe <service-name> --region=<region> \
+  --format="value(status.traffic)"
+curl https://<service-url>/health
+```
+
+## GKE / Kubernetes
+
+```bash
+# 1. Ver historial de rollouts
+kubectl rollout history deployment/<deployment-name> -n <namespace>
+
+# 2. Rollback a versión anterior (revision - 1)
+kubectl rollout undo deployment/<deployment-name> -n <namespace>
+
+# 3. Rollback a revision específica
+kubectl rollout undo deployment/<deployment-name> -n <namespace> --to-revision=<N>
+
+# 4. Monitorear rollback
+kubectl rollout status deployment/<deployment-name> -n <namespace>
+
+# 5. Verificar pods
+kubectl get pods -n <namespace> -l app=<app-name>
+kubectl logs -n <namespace> -l app=<app-name> --tail=50
+```
+
+## Feature Flag (kill switch inmediato sin redeploy)
+
+```bash
+# Unleash
+curl -X PATCH https://unleash.educabot.com/api/admin/features/<flag-name> \
+  -H "Authorization: <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"enabled": false}'
+
+# LaunchDarkly
+curl -X PATCH https://app.launchdarkly.com/api/v2/flags/<project>/<flag-key> \
+  -H "Authorization: <token>" \
+  -H "Content-Type: application/json" \
+  -d '[{"op": "replace", "path": "/environments/<env>/on", "value": false}]'
+```
+
+## GitHub Actions — Workflow de Rollback
+
+```yaml
+# .github/workflows/rollback.yml
+name: Rollback
+on:
+  workflow_dispatch:
+    inputs:
+      revision_sha:
+        description: 'Git SHA to roll back to'
+        required: true
+      service:
+        description: 'Service name'
+        required: true
+
+jobs:
+  rollback:
+    runs-on: ubuntu-latest
+    environment: production  # approval gate requerido
+    steps:
+      - name: Deploy previous image
+        run: |
+          gcloud run services update-traffic ${{ inputs.service }} \
+            --region=us-central1 \
+            --to-revisions=$(gcloud run revisions list \
+              --service=${{ inputs.service }} \
+              --filter="metadata.labels.commit-sha=${{ inputs.revision_sha }}" \
+              --format="value(name)" --limit=1)=100
+
+      - name: Notify Slack
+        uses: slackapi/slack-github-action@v1
+        with:
+          payload: |
+            {"text": "🔴 ROLLBACK ejecutado en ${{ inputs.service }} → SHA ${{ inputs.revision_sha }} por ${{ github.actor }}"}
+        env:
+          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_OPS_WEBHOOK }}
+```
+
+## Post-rollback — Pasos inmediatos
+
+```bash
+# 1. Capturar logs del período malo (antes de rotación)
+gcloud logging read \
+  "resource.type=cloud_run_revision AND timestamp>=\"$(date -u -d '30 minutes ago' +%Y-%m-%dT%H:%M:%SZ)\"" \
+  --limit=500 \
+  --format=json > incident-logs-$(date +%Y%m%d-%H%M%S).json
+
+# 2. Verificar health
+curl -sf https://<service-url>/health || echo "STILL DOWN"
+curl -sf https://<service-url>/ready || echo "NOT READY"
+
+# 3. Monitorear error rate (primeros 10 min post-rollback)
+watch -n 30 'gcloud logging read "resource.type=cloud_run_revision AND httpRequest.status>=500" \
+  --freshness=5m --format="value(httpRequest.status)" | wc -l'
+```
+
+## DB Data — PITR (Point-in-Time Recovery)
+
+```bash
+# Cloud SQL — restaurar a timestamp específico
+gcloud sql instances clone <instance-name> <new-instance-name> \
+  --point-in-time=$(date -u -d '15 minutes ago' +%Y-%m-%dT%H:%M:%SZ)
+
+# Verificar restore
+gcloud sql instances describe <new-instance-name> --format="value(state)"
+
+# Tiempo estimado: 30min–2h según tamaño. Documentar en runbook del servicio.
+# Luego: reconciliar writes entre restore point y now.
+```
+
+## Cache y CDN post-rollback
+
+```bash
+# Redis — invalidar todas las keys de app (si es necesario)
+redis-cli -h <host> --scan --pattern "app:*" | xargs redis-cli -h <host> DEL
+
+# Cloud CDN
+gcloud compute url-maps invalidate-cdn-cache <url-map> \
+  --path="/*" \
+  --async
+
+# Cloudflare
+curl -X POST "https://api.cloudflare.com/client/v4/zones/<zone_id>/purge_cache" \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  --data '{"purge_everything": true}'
+```

package/skills/run-migrations/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: run-migrations
+description: "Quick-reference para golang-migrate: crea migration up/down, corre pending, rollback last. Para schema design, zero-downtime, multi-tenant ver /data-migrations."
+category: "database"
+argument-hint: "[create <name> | up | down [N]]"
+user-invocable: true
+allowed-tools: Read, Bash
+---
+
+# Skill: run-migrations
+
+## Trigger
+
+When the user says "run migrations", "migrate", "crear migracion", "nueva migracion", "rollback migration", or similar.
+
+## Workflow
+
+### Modo: create new migration
+
+1. Ask for the migration name if not provided
+2. Generate the migration files:
+   ```bash
+   migrate create -ext sql -dir db/migrations -seq <migration_name>
+   ```
+3. This creates two files:
+   - `XXXXXX_<name>.up.sql` (apply changes)
+   - `XXXXXX_<name>.down.sql` (rollback changes)
+4. Help the user write the SQL for both files
+5. Remind the user to consult `/data-migrations` if the change affects production tables (zero-downtime patterns, locks, batching, online DDL)
+
+### Modo: run migrations
+
+1. Check the database connection string from `.env.local` or environment
+2. Run pending migrations:
+   ```bash
+   migrate -path db/migrations -database "$DATABASE_URL" up
+   ```
+3. Verify success — query `schema_migrations` table to confirm version
+
+### Modo: rollback
+
+1. Confirm with user before destructive rollback
+2. To rollback the last migration:
+   ```bash
+   migrate -path db/migrations -database "$DATABASE_URL" down 1
+   ```
+3. To rollback N migrations: `down N`
+
+## Prerequisites
+
+```bash
+go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@v4.17.0
+```
+
+## Notes
+
+- Always create both up and down migrations
+- Down migration should perfectly reverse the up migration
+- Use `IF EXISTS` / `IF NOT EXISTS` to make migrations idempotent
+- Test both up and down before committing
+- For Postgres-specific (CONCURRENTLY, partitioning, JSONB indexes) consult `postgres-specialist` agent
+- For zero-downtime patterns (expand-contract, online DDL, backfills) use `/data-migrations`
+
+## Recommended Next
+
+- `/data-migrations` for schema design and zero-downtime strategy
+- `postgres-specialist` agent for PG-specific migration patterns

package/skills/runbooks/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: runbooks
+description: "Crear y mantener runbooks operativos ejecutables para on-call. Paso-a-paso con comandos exactos para resolver incidentes sin depender del creador."
+category: "operations"
+argument-hint: "[create <name> | list | update <name>]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+---
+# Runbooks Operativos (Educabot)
+
+Runbook = documento ejecutable paso-a-paso para on-call. Objetivo: cualquier on-call resuelve sin depender del creador. Manual de vuelo a las 3am, no documentación narrativa.
+
+## 10 Secciones Obligatorias
+
+| # | Sección | Contenido |
+|---|---------|-----------|
+| 1 | Título + alert name | H1 = alert name literal de Alertmanager |
+| 2 | Severidad | SEV1 (>50% afectados), SEV2 (degradación parcial), SEV3 (informativa) |
+| 3 | Síntomas | Qué ve el usuario + qué dispara la alerta + links dashboards |
+| 4 | Impact assessment | Qué roto, a cuántos, desde cuándo. Horario escolar eleva +1 |
+| 5 | Diagnostic steps | **Comandos exactos copypasteables** con criterios de decisión |
+| 6 | Mitigation | Parar el sangrado: rollback revision / scale up |
+| 7 | Resolution | Fix permanente (puede ser en horas) |
+| 8 | Rollback plan | Qué hacer si el fix empeora |
+| 9 | Escalation path | Quién, en qué orden, con tiempos (15min/30min/45min) |
+| 10 | Post-incident | Link template postmortem, Jira action items, actualizar runbook |
+
+> → Read templates/runbook.md for the fill-in-the-blank runbook skeleton
+
+## Ubicación
+
+- `docs/runbooks/<service>/<alert-name>.md` — nombrado 1:1 con alert
+- Cada alert en Alertmanager debe tener `runbook_url` annotation
+- NUNCA solo en Notion/Confluence sin link desde la alerta
+
+## Runbooks Default Educabot
+
+Todo servicio debe tener al menos:
+- `high-error-rate-5xx.md`, `database-connection-exhausted.md`, `redis-down.md`
+- `cloud-run-deploy-failed.md`, `stripe-webhook-backlog.md`, `disk-space-critical.md`
+- `certificate-expiring.md`, `pubsub-consumer-lag.md`, `login-failures-spike.md`
+
+## Frontmatter
+
+```yaml
+owner: juan.perez@educabot.com
+service: alizia-api
+last_reviewed: 2026-04-10
+last_used_in_incident: 2026-03-28
+```
+
+## References
+
+> → Read references/writing-principles.md for runbook writing principles
+> → Read references/anti-patterns.md for common anti-patterns to avoid
+> → Read references/lifecycle.md for review cycle and automation progression
+> → Read references/checklist.md for the validation checklist

package/skills/runbooks/references/anti-patterns.md

@@ -0,0 +1,6 @@
+# Anti-patterns de Runbooks
+
+- Sin comandos exactos, tribal knowledge, sin criterios escalacion
+- Stale (1 ano sin update, URLs rotas), solo en wiki sin link desde alerta
+- 30 paginas ilegibles, sin rollback path, asumir contexto
+- Severidad ambigua sin criterios numericos, sin `runbook_url` en alerta

package/skills/runbooks/references/checklist.md

@@ -0,0 +1,13 @@
+# Checklist de Runbook
+
+- [ ] Alert name en H1 matchea Alertmanager
+- [ ] 10 secciones presentes en orden
+- [ ] Comandos copypasteables (proyecto, region, servicio hardcodeados)
+- [ ] Criterios de decision numericos
+- [ ] Escalation path con nombres + canales + tiempos
+- [ ] Links a dashboards funcionan
+- [ ] Rollback plan distinto del fix
+- [ ] Frontmatter: owner, service, last_reviewed
+- [ ] Alertmanager tiene `runbook_url`
+- [ ] Espanol LatAm, sin jerga sin explicar
+- [ ] Validado en drill o por alguien que no lo escribio

package/skills/runbooks/references/lifecycle.md

@@ -0,0 +1,14 @@
+# Ciclo de Vida de Runbooks
+
+## Review
+- Review obligatorio tras cada incident que uso el runbook
+- Audit trimestral: stale (>6 meses sin commit), URLs rotas, comandos que no corren
+- Drills trimestrales: simular escenario, medir si sirve
+
+## Automatizacion Progresiva
+
+```
+runbook manual -> script en repo -> cronjob -> auto-remediation (alerta -> webhook -> accion)
+```
+
+Aunque se automatice, el runbook describe el "por que" para cuando el script falle.

package/skills/runbooks/references/writing-principles.md

@@ -0,0 +1,9 @@
+# Principios de Escritura para Runbooks
+
+- **Comandos exactos**, no prosa ("gcloud run services describe alizia-api" no "chequear servicio")
+- **Criterios numericos** ("Si X>Y -> Z", no "si te parece raro")
+- **Escaneable a las 3am** — headers, code blocks, tablas, no parrafos
+- **Sin tribal knowledge** — no "preguntale a Juan", si "Juan P. en PagerDuty"
+- **Links directos** a dashboards, no "el dashboard principal"
+- **Espanol LatAm** — on-call regional
+- **Horario escolar importa** — 10am con clases != 3am