claude-code-arcane 1.0.0

package/skills/skill-auditor/references/lazy-loading-guide.md

@@ -0,0 +1,98 @@
+# MiniMax 3-Layer Lazy Loading Model
+
+Skills are loaded progressively to minimize token overhead per session. Every skill must be designed with this model in mind.
+
+## The Three Layers
+
+```
+Layer 1: Frontmatter         ~150 bytes/skill    Every session
+Layer 2: SKILL.md body        ~2-8 KB/skill      On invocation only
+Layer 3: references/           Unbounded          When skill references them
+```
+
+### Layer 1 -- Frontmatter (always loaded)
+
+The YAML frontmatter block (between `---` markers) is the only part loaded at session start. Claude Code reads all SKILL.md frontmatter blocks to build its skill registry.
+
+**Budget**: ~7 KB total for 45 skills, ~25 KB for 150+ skills.
+
+**Rules**:
+- Keep frontmatter minimal: only the 5 required fields + optional `argument-hint`
+- Never put instructions, examples, or documentation in frontmatter
+- Description must be concise (under 200 chars) -- it is loaded every session
+
+### Layer 2 -- SKILL.md body (loaded on invocation)
+
+The full SKILL.md content (below the closing `---`) loads only when the user invokes the skill. This is the skill's main instruction set.
+
+**Budget**: Under 200 lines (~8 KB) per skill.
+
+**Rules**:
+- Keep the actionable instructions in the SKILL.md body
+- Structure with clear `##` phase/step headings
+- If content exceeds 200 lines, extract to Layer 3
+- Do NOT put reference tables, long code examples, or troubleshooting guides inline
+
+### Layer 3 -- references/ and templates/ (loaded on demand)
+
+Heavy reference material lives in subdirectories next to SKILL.md. The skill body points to them with relative references; Claude reads them only when the specific section is needed.
+
+**Budget**: Unbounded -- these files only load when explicitly referenced.
+
+**Rules**:
+- Create a `references/` subdirectory for extracted reference material
+- Create a `templates/` subdirectory for file templates the skill generates
+- Use a one-line pointer in SKILL.md: `> See references/section-name.md for details.`
+- Name files descriptively: `references/api-patterns.md`, `templates/dockerfile.md`
+
+## When to Extract to Layer 3
+
+Extract a section from SKILL.md to `references/` when:
+
+| Condition | Action |
+|-----------|--------|
+| Section is over 50 lines | Extract to `references/<topic>.md` |
+| Section is a lookup table | Extract to `references/<table-name>.md` |
+| Section contains code templates | Extract to `templates/<template-name>.md` |
+| Section is troubleshooting/FAQ | Extract to `references/troubleshooting.md` |
+| Section is "how X works" background | Extract to `references/<concept>.md` |
+| SKILL.md total exceeds 200 lines | Mandatory -- extract until under 200 |
+
+## Extraction Procedure
+
+1. Identify the section to extract (must be self-contained, not interleaved with instructions)
+2. Create the target file: `references/<descriptive-name>.md`
+3. Move the content verbatim (keep formatting, headings adjusted to start at `#`)
+4. Replace the original section in SKILL.md with:
+
+```markdown
+### Section Title
+
+> See `references/descriptive-name.md` for the full reference.
+```
+
+5. Verify SKILL.md is now under 200 lines
+6. Verify the extracted file is readable standalone (has a title, makes sense without SKILL.md context)
+
+## Directory Layout Example
+
+```
+skills-backend/api-design/
+  SKILL.md                          # ~150 lines (Layer 2)
+  references/
+    api-style-decision-matrix.md    # 80 lines (Layer 3)
+    rest-conventions.md             # 120 lines (Layer 3)
+    error-format-rfc7807.md         # 45 lines (Layer 3)
+  templates/
+    openapi-skeleton.yaml           # Template file (Layer 3)
+```
+
+## Token Impact Summary
+
+| Scenario | 45 skills | 150 skills | 300 skills |
+|----------|-----------|------------|------------|
+| Layer 1 only (session start) | ~7 KB | ~25 KB | ~50 KB |
+| Layer 1 + one Layer 2 invocation | ~15 KB | ~33 KB | ~58 KB |
+| Layer 1 + Layer 2 + Layer 3 refs | ~25 KB | ~43 KB | ~68 KB |
+
+Keeping SKILL.md under 200 lines ensures that even with 300+ skills, a single invocation stays under 60 KB of context -- well within Claude's working memory.

package/skills/skill-improve/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: skill-improve
+description: "Improve a skill using a test-fix-retest loop. Runs static checks, proposes targeted fixes, rewrites the skill, re-tests, and keeps or reverts based on score change."
+category: "workflow"
+argument-hint: "[skill-name]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write, Bash
+---
+
+# Skill Improve
+
+Test → fix → retest → keep or revert loop on a single skill.
+
+## Phase 1: Parse Argument
+
+Read skill name from first arg. Verify `skills/[name]/SKILL.md` exists. If missing → stop.
+
+## Phase 2: Baseline Test
+
+Run `/skill-test static [name]`. Record FAILs, WARNs, which checks failed (1-7).
+
+### Phase 2b: Category Baseline
+
+Look up `category:` in `catalog.yaml`. If not assigned → skip. If found, run `/skill-test category [name]`, record category FAILs/WARNs. If both baselines are 0 FAILs + 0 WARNs → stop ("already passes all checks").
+
+## Phase 3: Diagnose
+
+Read full skill file. For each failing/warning check, identify exact gap:
+
+| Check | Gap if failing |
+|-------|---------------|
+| 1 | Missing frontmatter field |
+| 2 | Fewer phases than minimum |
+| 3 | No verdict keywords in body |
+| 4 | Write/Edit in tools but no ask-before-write language |
+| 5 (warn) | No follow-up/next-step section |
+| 6 (warn) | `context: fork` with <5 phases |
+| 7 (warn) | argument-hint empty or mismatched with modes |
+
+For category checks: identify text gaps (e.g., G2: missing director prompts, A2: no per-section May-I-write, T3: BLOCKED not surfaced). Show full diagnosis before proposing changes.
+
+## Phase 4: Propose Fix
+
+Targeted fix per failure/warning as before/after blocks. Only change what's failing. Ask to write improved version.
+
+## Phase 5: Write and Retest
+
+Save current content for revert. Write improved skill. Re-run static (+ category if applicable). Display comparison: Before → After for both dimensions.
+
+## Phase 6: Verdict
+
+- **Combined score improved** → "Changes kept." Show what was fixed.
+- **Same or worse** → "Score did not improve." Ask to revert via `git checkout`.
+
+## Phase 7: Next Steps
+
+- `/skill-test static all` to find next skill with failures
+- `/skill-improve [next-name]` to continue loop
+- `/skill-test audit` for overall coverage

package/skills/skill-test/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: skill-test
+description: "Validate skill files for structural compliance and behavioral correctness. Three modes: static (linter), spec (behavioral), audit (coverage report)."
+category: "testing"
+argument-hint: "static [skill-name | all] | spec [skill-name] | category [skill-name | all] | audit"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Write
+---
+
+# Skill Test
+
+Validates `skills/*/SKILL.md` for structural compliance and behavioral correctness.
+
+## Modes
+
+| Mode | Command | Purpose | Cost |
+|------|---------|---------|------|
+| `static` | `/skill-test static [name\|all]` | 7 structural checks per skill | Low (~1k/skill) |
+| `spec` | `/skill-test spec [name]` | Behavioral assertions from test spec | Medium (~5k/skill) |
+| `category` | `/skill-test category [name\|all]` | Category-specific rubric metrics | Low (~2k/skill) |
+| `audit` | `/skill-test audit` | Coverage report — skills, agents, test dates | Low (~3k total) |
+
+## Phase 1: Parse Arguments
+
+`static [name]` → 7 checks on one skill. `static all` → all skills (Glob `skills/*/SKILL.md`). `spec [name]` → read skill + test spec, evaluate assertions. `category [name|all]` → category rubric from `CCGS Skill Testing Framework/quality-rubric.md`. `audit` (or no arg) → read catalog, list all, show coverage. Missing/unrecognized → output usage and stop.
+
+## Phase 2A: Static Mode
+
+> → Read references/static-checks.md for the 7 structural validation checks and verdict criteria
+
+## Phase 2B: Spec Mode
+
+> → Read references/spec-mode-procedure.md for behavioral testing procedure
+
+## Phase 2D: Category Mode
+
+> → Read references/category-mode-procedure.md for rubric evaluation procedure
+
+## Phase 2C: Audit Mode
+
+> → Read references/audit-mode-procedure.md for coverage report procedure
+
+## Phase 3: Next Steps
+
+> → Read references/next-steps-guide.md for post-run suggestions by mode

package/skills/skill-test/references/audit-mode-procedure.md

@@ -0,0 +1,7 @@
+# Audit Mode — Coverage Report Procedure
+
+1. Read `CCGS Skill Testing Framework/catalog.yaml`
+2. Glob all skills + read agents section from catalog
+3. Build coverage tables: has spec, last static/spec/category dates+results, priority
+4. Output report with skill table + agent table + priority gaps summary
+5. Offer follow-up: `static all`, `category all`, or `spec [name]`

package/skills/skill-test/references/category-mode-procedure.md

@@ -0,0 +1,7 @@
+# Category Mode — Rubric Evaluation Procedure
+
+1. Locate skill + `category:` from catalog.yaml. `utility` category: evaluate U1 (static) + U2 (gate mode) only
+2. Read rubric section from `CCGS Skill Testing Framework/quality-rubric.md`
+3. Read skill fully, evaluate each rubric metric: PASS / FAIL / WARN with gap description
+4. Output report with per-metric results + fix recommendations
+5. Offer to update catalog.yaml (`last_category`, `last_category_result`)

package/skills/skill-test/references/next-steps-guide.md

@@ -0,0 +1,9 @@
+# Next Steps Guide
+
+| After | Suggest |
+|-------|---------|
+| `static [name]` | `spec [name]` |
+| `static all` with failures | Address NON-COMPLIANT first |
+| `spec` PASS | Update catalog, find next spec gap |
+| `spec` FAIL | Review failing assertions, update skill or spec |
+| `audit` | Start with critical-priority gaps, use spec template |

package/skills/skill-test/references/spec-mode-procedure.md

@@ -0,0 +1,8 @@
+# Spec Mode — Behavioral Testing Procedure
+
+1. Locate skill at `.claude/skills/[name]/SKILL.md` + spec path from `CCGS Skill Testing Framework/catalog.yaml`
+2. Read both files completely
+3. For each test case: read fixture, expected behavior, assertions. Mark each PASS / PARTIAL / FAIL via reasoning evaluation
+4. Protocol compliance: "May I write" before writes, findings before approval, next-step handoff, no auto-create files
+5. Output report with per-case verdicts + protocol compliance + overall verdict
+6. Offer to write results to `CCGS Skill Testing Framework/results/` and update catalog.yaml (`last_spec`, `last_spec_result`)

package/skills/skill-test/references/static-checks.md

@@ -0,0 +1,13 @@
+# Static Checks — 7 Structural Validations
+
+| Check | What | Verdict |
+|-------|------|---------|
+| 1 — Frontmatter | `name`, `description`, `argument-hint`, `user-invocable`, `allowed-tools` present | FAIL if any absent |
+| 2 — Phases | >=2 numbered phase headings (`## Phase N`, `## N.`, or >=2 `##` headings) | FAIL if <2 |
+| 3 — Verdict Keywords | Contains >=1 of: PASS, FAIL, CONCERNS, APPROVED, BLOCKED, COMPLETE, READY, COMPLIANT, NON-COMPLIANT | FAIL if none |
+| 4 — Collaborative Protocol | "May I write" / "before writing" / "approval" near file-write instructions | WARN if absent; FAIL if `allowed-tools` includes Write/Edit but no ask-before-write |
+| 5 — Next-Step Handoff | Final section mentions another skill, "next step", or follow-up | WARN if absent |
+| 6 — Fork Complexity | If `context: fork`, must have >=5 phase headings | WARN if <5 |
+| 7 — Argument Hint | Non-empty; documented modes should match hint | WARN if empty or mismatch |
+
+**Output:** per-skill table of check results + verdict (COMPLIANT / WARNINGS / NON-COMPLIANT). For `static all`: summary table + aggregate counts.

package/skills/slack/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: slack
+description: "Manage Slack via Web API: send messages, create channels, upload files, search history, webhooks."
+category: "integrations"
+argument-hint: "[send|channel|file|search] <args>"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash
+---
+# Slack Manager
+
+Web API: `https://slack.com/api/`. Auth: `Bearer $SLACK_BOT_TOKEN`. Scopes: `chat:write`, `channels:read`, `users:read`, `files:write`. Webhooks simples (sin bot): POST a `hooks.slack.com/services/...`.
+
+## API Operations
+
+| Operation | Method | Endpoint | Key fields |
+|-----------|--------|----------|------------|
+| Send message | POST | `/chat.postMessage` | channel (ID o #name), text, blocks (Block Kit) |
+| Thread reply | POST | `/chat.postMessage` | + `thread_ts` del mensaje padre |
+| Upload file | POST | `/files.upload` | channels, file (@path), title, initial_comment |
+| Search messages | GET | `/search.messages` | query, count. Requiere user token (no bot) |
+| Create channel | POST | `/conversations.create` | name, is_private |
+| Invite users | POST | `/conversations.invite` | channel, users (comma-separated IDs) |
+| Find user by email | GET | `/users.lookupByEmail` | email |
+
+## Block Kit essentials
+
+Header (`plain_text`), section (`mrkdwn`), divider, context (elements array), actions (buttons con URL). Compose visualmente en Block Kit Builder.
+
+## Comandos
+
+| Comando | Qué hace |
+|---------|----------|
+| `/slack send <channel> "msg"` | Mensaje simple |
+| `/slack release <version> [channels]` | Announcement: header, features, fixes, changelog link, deployer |
+| `/slack incident <sev> <summary>` | SEV header + thread. SEV-1/2: crear canal `#inc-{date}-{name}` |
+| `/slack broadcast "msg" [#ch1 #ch2]` | Multi-channel |
+| `/slack search "query" [--since 7d]` | Search + summarize |
+
+## Reglas
+
+- **NUNCA** `@channel` o `@here` sin autorización explícita
+- Rate limit: ~1 msg/s por canal, 50+ req/min API
+- DMs via channel ID (tipo `D...`), no username
+- Legacy tokens no existen — todos bot tokens scoped
+- Interactive components (buttons, modals) requieren servidor HTTP — fuera de scope

package/skills/slo-sli/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: slo-sli
+description: "Define and operate SLIs, SLOs, and error budgets for Educabot services (Go + TS, GCP, Prometheus). Trigger: SLO, SLI, error budget, burn rate."
+category: "observability"
+stack: Go, TypeScript, Prometheus, GCP Cloud Monitoring, Terraform, Alertmanager
+context: Educabot EdTech LatAm — servicios con peak en horario escolar AM
+argument-hint: "[service-name] [--availability|--latency|--error]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+metadata:
+  category: reliability
+  sources:
+    - Google SRE Handbook (sre.google/sre-book)
+    - Google SRE Workbook — Implementing SLOs
+    - OpenSLO Specification (openslo.com)
+    - DORA Metrics (dora.dev)
+---
+# SLO / SLI — Reliability Objectives
+
+Definir, medir y alertar SLIs/SLOs en servicios Educabot. Google SRE Workbook + realidad EdTech LatAm (peak escolar AM).
+
+## Cuándo usar / NO usar
+
+| Usar | NO usar |
+|------|---------|
+| Definir objetivos confiabilidad servicio nuevo/existente | Scripts internos, jobs one-shot, prototipos |
+| Alertas por burn rate (reemplazar fixed-threshold) | Métricas infra (CPU/RAM/GC) — son causas, no SLIs |
+| Negociar velocity vs estabilidad con producto | Antes de tener baseline real (≥2-4 semanas métricas) |
+| Review trimestral SLOs | |
+| Justificar feature freeze por error budget agotado | |
+
+## Conceptos
+
+| Término | Definición | Ejemplo |
+|---------|-----------|---------|
+| **SLI** | Métrica observable user-facing | Fracción requests con status <500 y latencia <500ms |
+| **SLO** | Target sobre SLI en ventana | 99.9% requests cumplen SLI en 30 días |
+| **SLA** | Compromiso contractual con penalidades | 99.5% uptime mensual en contrato B2B |
+| **Error budget** | `100% - SLO` = downtime permitido | SLO 99.9% → 0.1% → ~43 min/mes |
+
+**Regla:** `SLA < SLO < SLI real`. SLA tiene colchón sobre SLO, SLO se fija por debajo del desempeño observado.
+
+## Buenos SLIs (defaults Educabot)
+
+| Familia | Qué mide | Notas |
+|---------|----------|-------|
+| **Availability** | Fracción requests sin 5xx | Request-based, PromQL rate |
+| **Latency** | p95/p99 bajo umbral | Nunca solo p50 — la cola es donde vive el user pain |
+| **Quality** | Tasa éxito transacciones negocio | login, checkout, grade_submit success/attempts |
+| **Freshness** | Lag último record procesado | Para pipelines de datos: lag <300s |
+
+## Tiers de servicio
+
+| Tier | Descripción | Availability | Latency p95 |
+|------|-------------|-------------|-------------|
+| **Tier-1** | Login, API core, grading en vivo | 99.95% | <300ms |
+| **Tier-2** | Reportes, dashboards docentes | 99.5% | <1s |
+| **Tier-3** | Background jobs, exports, analytics | 99% | N/A (batch) |
+
+**Ventana horaria Educabot:** Tier-1 en horario escolar (07-18 UTC-3, L-V): 99.99%. Fuera: 99.9%. 5min caídos martes 09:00 duele 100x más que domingo 03:00.
+
+## Error budget policy
+
+| Budget remaining | Acción |
+|-----------------|--------|
+| >50% | Velocidad normal, features OK |
+| 10-50% | Precaución, reforzar canary/staged rollouts |
+| <10% | **Freeze features**, foco estabilidad |
+| 0% (agotado) | Freeze + postmortem blameless → `/incident` |
+
+Firmado por ingeniería + producto. Sin firma de producto, no hay SLO — hay wishlist.
+
+## Alerting multi-window multi-burn-rate
+
+Dos alertas por SLO: fast burn (page, 14.4x) + slow burn (ticket, 6x). Prometheus recording rules + Alertmanager.
+
+> → Read references/alerting-burn-rate.md for fórmulas, GCP Terraform, dashboard y review trimestral
+
+## Anti-patterns
+
+> → Read references/anti-patterns.md for lista completa (10 items)
+
+## Checklist
+
+> → Read references/checklist.md for checklist completo (12 items)
+
+## Delegación
+
+- `/incident` — postmortem tras budget exhaustion
+- `/audit-dev` — auditoría observabilidad existente
+- `/scaffold-go` — scaffolding Go con Prometheus client
+- `/deploy-check` — pre-deploy que impacte SLO

package/skills/slo-sli/references/alerting-burn-rate.md

@@ -0,0 +1,22 @@
+# Alerting Multi-window Multi-burn-rate
+
+Reemplaza fixed-threshold. Dos alertas por SLO:
+
+- **Fast burn (page):** ventana 5min+1h, burn rate 14.4x -> consume 2% budget en 1h. Page a on-call.
+- **Slow burn (ticket):** ventana 30min+6h, burn rate 6x -> consume 10% budget en 6h. Ticket no-urgente.
+
+Implementar con Prometheus recording rules (pre-compute error ratios a 5m, 1h, 30m, 6h) + Alertmanager rules. Formula: threshold = `burn_rate x (1 - SLO)`. Ej: SLO 99.9% -> `14.4 x 0.001 = 0.0144`.
+
+## GCP Cloud Monitoring (Terraform)
+
+Alternativa nativa si ya usas Cloud Monitoring: `google_monitoring_custom_service` + `google_monitoring_slo` (request_based_sli, rolling_period_days 30) + `google_monitoring_alert_policy` (select_slo_burn_rate, threshold 14.4).
+
+## Dashboard interno
+
+Publico para producto + ingenieria. Minimo: SLO actual (30d rolling) por servicio/tier, error budget remaining (%, minutos), burn rate actual (1h, 6h), top 5 endpoints que mas budget consumen, historial incidentes con link postmortem.
+
+## Review trimestral
+
+- **Sobrecumple consistente** (ej: SLO 99.9% real 99.99% 2 trimestres): SLO laxo, subir o permitir mas experimentacion
+- **Incumple consistente:** target irreal o deuda tecnica, bajar SLO temporalmente + plan mejora
+- **Flujos cambiaron:** reevaluar que SLIs importan

package/skills/slo-sli/references/anti-patterns.md

@@ -0,0 +1,12 @@
+# Anti-patterns — SLO/SLI
+
+- SLO 100% — imposible, desincentiva deploys
+- SLI infra-centric (CPU/RAM) — no es experiencia de usuario
+- Sin error budget policy — SLO decorativo
+- SLO sin baseline real — primero medis, despues prometes
+- Solo p50 — ignora cola
+- Ventana corta (5min) sin larga (30d) — pierde drain lento
+- Una sola alerta fixed-threshold — fatiga garantizada
+- SLOs sin owner — nadie los revisa
+- Mismo SLO para todos los servicios
+- Ignorar contexto temporal (horario escolar)

package/skills/slo-sli/references/checklist.md

@@ -0,0 +1,14 @@
+# Checklist por Servicio — SLO/SLI
+
+- [ ] Servicio clasificado por tier (1/2/3)
+- [ ] SLIs definidos: availability + latency minimo; quality/freshness si aplica
+- [ ] Baseline medido (>=2-4 semanas)
+- [ ] SLO firmado por ingenieria + producto
+- [ ] Error budget policy escrita y linkeada
+- [ ] Owner asignado (equipo, no persona)
+- [ ] Recording rules Prometheus desplegadas
+- [ ] Alertas multi-burn-rate (fast + slow) configuradas
+- [ ] SLO visible en dashboard interno
+- [ ] Runbook linkeado desde cada alerta
+- [ ] Review trimestral calendarizado
+- [ ] Ventana horaria escolar considerada (tier-1)

package/skills/smoke-check/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: smoke-check
+description: "Critical path smoke test gate before QA hand-off. Runs automated tests, verifies core functionality, PASS/FAIL report."
+category: "testing"
+argument-hint: "[sprint | quick | --platform pc|console|mobile|all]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, AskUserQuestion
+---
+# Smoke Check
+
+Gate between "implementation done" and "ready for QA". **A build that fails smoke check does not go to QA.**
+
+Output: `production/qa/smoke-[date].md`
+
+## Arguments
+
+- `sprint` (default): full smoke check against current sprint stories
+- `quick`: skip coverage scan (Phase 3) and Batch 3
+- `--platform pc|console|mobile|all`: add platform-specific checks
+
+## Phase 1: Detect Environment
+
+1. Verify `tests/` exists (else stop → `/test-setup`)
+2. Check CI workflow for test refs
+3. Read engine from `.claude/docs/technical-preferences.md`
+4. Load smoke test list from `production/qa/smoke-tests.md` or `tests/smoke/`
+5. Load QA plan from `production/qa/qa-plan-*.md` (most recent)
+
+Report: engine, test dir, CI status, QA plan path.
+
+## Phase 2: Run Automated Tests
+
+- **Unity/Unreal:** Check for test result artifacts (XML/JSON). If none → request manual confirmation
+- Parse: total, passing, failing, failure names (up to 10)
+- **NOT RUN ≠ FAIL** — record as warning, developer confirms manually
+
+## Phase 3: Test Coverage (skip if `quick`)
+
+For each story in scope: glob `tests/unit/[system]/` and `tests/integration/[system]/`
+
+| Status | Meaning |
+|--------|---------|
+| COVERED | Test file found matching story |
+| MANUAL | Visual/Feel story with evidence doc |
+| MISSING | Logic story without test (advisory, not FAIL) |
+| EXPECTED | Config/Data story, no test required |
+
+## Phase 4: Manual Smoke Checks (AskUserQuestion, max 3 batches)
+
+| Batch | Content | When |
+|-------|---------|------|
+| 1 — Core stability | Launch, new game, menu inputs | Always |
+| 2 — Sprint changes | Primary mechanic, regressions | Always |
+| 3 — Data/perf | Save/load, frame rate | Unless `quick` |
+| Platform batches | PC/console/mobile specific | If `--platform` |
+
+## Phase 5: Verdict
+
+| Verdict | Criteria |
+|---------|----------|
+| **FAIL** | Automated tests failed, OR any Batch 1/2 FAIL |
+| **PASS WITH WARNINGS** | Tests pass/NOT RUN, all Batch 1/2 pass, but MISSING coverage |
+| **PASS** | All tests pass, all checks pass, no MISSING coverage |
+
+## Phase 6: Write & Gate
+
+Present report → ask approval → write to `production/qa/smoke-[date].md`
+
+- FAIL: list failures, "fix and re-run before QA"
+- PASS (WITH WARNINGS): "ready for QA", list advisory items
+- PASS: "ready for QA, share qa-plan with qa-tester"
+
+## Protocol
+- NOT RUN = warning, not auto-FAIL. Developer confirms manually
+- Never auto-fix failures — report only
+- PASS WITH WARNINGS doesn't block QA hand-off
+- Never write report without explicit approval

package/skills/snowflake-development/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: snowflake-development
+description: "Snowflake SQL, data pipelines (Dynamic Tables, Streams+Tasks), Cortex AI functions, Snowpark Python, and dbt integration. Covers the colon-prefix rule, semi-structured data, MERGE upserts, performance tuning, and security hardening."
+argument-hint: ""
+category: "backend"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit
+---
+
+# Snowflake Development
+
+Snowflake SQL, data pipelines, Cortex AI, and Snowpark Python development. Covers the colon-prefix rule, semi-structured data, MERGE upserts, Dynamic Tables, Streams+Tasks, Cortex AI functions, agent specs, performance tuning, and security hardening.
+
+> **Note:** This skill may create or modify files in your project. It will ask before writing.
+
+## Quick Start
+
+```bash
+# Generate a MERGE upsert template
+python scripts/snowflake_query_helper.py merge --target customers --source staging_customers --key customer_id --columns name,email,updated_at
+
+# Generate a Dynamic Table template
+python scripts/snowflake_query_helper.py dynamic-table --name cleaned_events --warehouse transform_wh --lag "5 minutes"
+
+# Generate RBAC grant statements
+python scripts/snowflake_query_helper.py grant --role analyst_role --database analytics --schemas public,staging --privileges SELECT,USAGE
+```
+
+## SQL Best Practices
+
+### Naming and Style
+
+- Use `snake_case` for all identifiers. Avoid double-quoted identifiers.
+- Use CTEs (`WITH` clauses) over nested subqueries.
+- Use `CREATE OR REPLACE` for idempotent DDL.
+- Use explicit column lists -- never `SELECT *` in production.
+
+### Stored Procedures -- Colon Prefix Rule
+
+In SQL stored procedures (BEGIN...END blocks), variables and parameters **must** use the colon `:` prefix inside SQL statements. Without it, Snowflake treats them as column identifiers.
+
+```sql
+-- WRONG: missing colon prefix
+SELECT name INTO result FROM users WHERE id = p_id;
+
+-- CORRECT: colon prefix on both variable and parameter
+SELECT name INTO :result FROM users WHERE id = :p_id;
+```
+
+### Semi-Structured Data
+
+- VARIANT, OBJECT, ARRAY for JSON/Avro/Parquet/ORC.
+- Access nested fields: `src:customer.name::STRING`. Always cast with `::TYPE`.
+- Flatten arrays: `SELECT f.value:name::STRING FROM my_table, LATERAL FLATTEN(input => src:items) f;`
+
+## Data Pipelines
+
+| Approach | When to Use |
+|----------|-------------|
+| Dynamic Tables | Declarative transformations. **Default choice.** Define the query, Snowflake handles refresh. |
+| Streams + Tasks | Imperative CDC. Use for procedural logic, stored procedure calls, complex branching. |
+| Snowpipe | Continuous file loading from cloud storage (S3, GCS, Azure). |
+
+### Dynamic Tables -- Key Rules
+
+- Set `TARGET_LAG` progressively: tighter at the top of the DAG, looser downstream.
+- Incremental DTs cannot depend on Full-refresh DTs.
+- `SELECT *` breaks on upstream schema changes -- use explicit column lists.
+
+### Streams + Tasks -- Key Rule
+
+Tasks start SUSPENDED. You **must** resume: `ALTER TASK task_name RESUME;`
+
+## Cortex AI
+
+| Function | Purpose |
+|----------|---------|
+| `AI_COMPLETE` | LLM completion (text, images, documents) |
+| `AI_CLASSIFY` | Classify text into categories (up to 500 labels) |
+| `AI_FILTER` | Boolean filter on text or images |
+| `AI_EXTRACT` | Structured extraction from text/images/documents |
+| `AI_SENTIMENT` | Sentiment score (-1 to 1) |
+| `AI_PARSE_DOCUMENT` | OCR or layout extraction from documents |
+| `AI_REDACT` | PII removal from text |
+
+**Deprecated names (do NOT use):** `COMPLETE`, `CLASSIFY_TEXT`, `EXTRACT_ANSWER`, `PARSE_DOCUMENT`, `SUMMARIZE`, `TRANSLATE`, `SENTIMENT`, `EMBED_TEXT_768`.
+
+### TO_FILE -- Common Pitfall
+
+Stage path and filename are **separate** arguments: `TO_FILE('@db.schema.mystage', 'invoice.pdf')` (not `TO_FILE('@stage/file.pdf')`).
+
+## Proactive Triggers
+
+Surface these issues without being asked when you notice them in context:
+
+- **Missing colon prefix** in SQL stored procedures
+- **`SELECT *` in Dynamic Tables** -- schema-change time bomb
+- **Deprecated Cortex function names** -- suggest `AI_*` equivalents
+- **Task not resumed** after creation
+- **Hardcoded credentials** in Snowpark code
+
+## Common Errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| "Object does not exist" | Wrong database/schema context or missing grants | Fully qualify names, check grants |
+| "Invalid identifier" in procedure | Missing colon prefix on variable | Use `:variable_name` |
+| "Numeric value not recognized" | VARIANT field not cast | Cast explicitly: `src:field::NUMBER(10,2)` |
+| Task not running | Forgot to resume after creation | `ALTER TASK task_name RESUME;` |
+| DT refresh failing | Schema change upstream | Use explicit columns, verify change tracking |
+| TO_FILE error | Combined path as single argument | Split into two args |
+
+## Reference Documentation
+
+| Document | Contents |
+|----------|----------|
+| `references/snowflake_sql_and_pipelines.md` | SQL patterns, MERGE templates, Dynamic Table debugging, Snowpipe, anti-patterns |
+| `references/cortex_ai_and_agents.md` | Cortex AI functions, agent spec structure, Cortex Search, Snowpark |
+| `references/troubleshooting.md` | Error reference, debugging queries, common fixes |