luana-method

Generate, audit, and compress AI-optimized documentation for codebases. This skill applies research-backed principles from three peer-reviewed papers to create documentation that maximizes AI agent performance instead of degrading it. Use this skill whenever the user asks to "write docs", "create a CLAUDE.md", "document a module", "audit documentation", "compress docs", "optimize docs for AI", "write module docs", "create domain documentation", "review doc quality", or mentions documentation bloat, token waste, or AI context efficiency. Also trigger when the user references "ai-docs principles", "telegram style docs", or wants to apply the "Lost in the Middle", "Less is More", or "AGENTS.md" research findings.

Architect orchestrator Luana v4 (post pm-redesign 2026-05 Punto 4). Lee 01-spec.md (de /po-ux o /po) + 02-design-agentic.md (si agentic) en stories state=refined. Decide qué surfaces toca (BE/FE/agentic). Spawna `architect-orchestrator` (single agent type, full-stack) que internamente carga las skills `architect-be` + `architect-fe` + `architect-agentic` según surface — produce 03-arch.md consolidado + 03-arch-{be,fe,agentic}.md por surface en una sola pasada. Reúne y produce el READY PACKAGE: 03-arch.md (consolidado) + 04-validators.yaml (★CRITICAL — pytest/playwright/shell commands must_pass:true ejecutables, 4 categories: non_functional/functional/visual/agentic_eval) + 05-guidelines.md (patterns required/forbidden + files in scope) + 06-tickets.yaml (work units atómicos). Cierra story state refined → ready. Activa cuando user dice: '/architect', 'diseñemos la arq', 'tickets', 'qué tickets salen', 'arquitectura técnica', 'cómo lo construimos técnicamente', 'cerrá el ready package'.

Auditor independiente v4 (Conv 3 — Review+Merge, post pm-redesign 2026-05 Punto 4 + story-closure-gate 2026-05-18). Toma story state=developed (AUTO-HANDOFF /dev-team default; manual opt-in via defer_audit:true) → transition state=developed→reviewing → spawna auditor-{be,fe,agentic} según surface. Phase D NEW: gherkin verification matrix (cada scenario 01-spec.md → test path → status, escribe 06-audit/gherkin-matrix.md). Veredicto: APPROVED | CHANGES_REQUESTED | ESCALATED. Self-fix triviales (lint/typo/format) cap 2 iter. Diseño/security/arch → escala. Cuando todos tickets audit-passed, escribe CHECKPOINTS.md (C1-C5 grid: Code | Spec | Architecture | Cross-cutting | Trace) + AUTO-HANDOFF /pm-{brand} merge. Activa cuando user dice: '/auditor', 'audita story', 'revisa tickets', 'verdict', 'review final', 'CHECKPOINTS'.

Implements FastAPI endpoints, creates SQLAlchemy 2.0 async models, generates idempotent Alembic migrations, structures bounded contexts following DDD (domain→infrastructure→application→api), and produces typed Pydantic v2 DTOs. Runs inside Docker (visionarias_brain_dev). Use when: 'create an endpoint', 'modify the backend', 'create a new entity', 'update a service', 'database logic', 'fix a backend bug', 'add a migration', 'create a repository', 'agrega un campo', 'nueva ruta API', 'corrige el servicio', or any Python/FastAPI/SQLAlchemy/Alembic task.

Stage + commit + push delegation a Haiku worker (token-cheap pattern, origen 2026-05-09). Orchestrator (Opus) prepara plan; Haiku ejecuta git workflow con guardrails verbatim. Activa: '/commit-push', 'commitea y sube', 'commit haiku', 'commit y push', 'commit + push'.

Use when creating social media content ideas, hunting for viral references, adapting content formulas from other niches/countries, or planning content calendars. Generates hook variations, writes caption drafts, curates cross-niche reference swipe files, scores references with STEPPS framework, produces complete content briefs, and builds weekly posting schedules — all grounded in brand and offer data. Integrates with Brand Studio (positioning, narrative, voice) and Offer Studio (promise, audience psychology). Triggers: 'contenido', 'content', 'ideas de contenido', 'reel', 'carrusel', 'post', 'viral', 'qué publico', 'dame ideas', 'inspiración', 'referencia', 'steal like an artist', 'calendario de contenido', 'qué posteo', 'ideas para Instagram', 'ideas para TikTok', 'content hunting'.

Use cuando reportes/investigues bug del copilot module: loops infinitos, cards faltantes, conversaciones vacías al refresh, extracción que falla, trazas que mienten, tools que no ejecutan, costos disparados, routing equivocado, prompt cache roto, mutaciones que no persisten, channel format ignorado, voseo en outputs. Activa también para extender (agregar provider, tool, workflow, channel, KB chunk) sin romper invariantes. Triggers: 'bug copilot', 'loop copilot', 'card no aparece', 'conversación vacía', 'documento no extrae', 'agente no responde', 'tool no ejecuta', 'trazas mienten', 'tokens burned', 'extract_document_to_fields falla', 'propose_field_updates no persiste', 'format_for_channel ignored', 'voseo en respuesta', 'cache hit rate', 'cuántos tokens', 'agregar provider', 'agregar workflow', 'agregar tool transversal', 'agregar canal'.

Use when building data-heavy screens, analytics dashboards, metric visualizations, or inline charts for Copilot. Creates bar/line charts, renders data tables, aggregates KPI metrics, builds filterable dashboard layouts, and generates HTML previews for concept validation. Triggers: 'dashboard', 'métricas', 'gráfico', 'chart', 'visualización', 'analytics', 'KPI', 'reporte', 'muestra los datos', 'cómo van los números'.

Developer team router v4 (Conv 2 — autonomous build, post pm-redesign 2026-05 Punto 4 + story-closure-gate 2026-05-18). Reads ready package (01-spec.md + 03-arch.md + 04-validators.yaml + 05-guidelines.md + 06-tickets.yaml) en docs/product/stories/{story-id}/ state=ready. Itera ticket-por-ticket: implement → run validators (4 categorías: non_functional/functional/visual/agentic_eval) → fix targeted file → repeat hasta GREEN o cap_reached. Decide owner según owner_eligibility + production_code flag (R23). qwen-opencode/Sonnet preferido para BE/FE no-agentic + tests/docs sobre agentic. Opus 4.7 obligatorio para AGENTIC production code. Mantiene T-{n}-impl-log.md vivo. TDD obligatorio. On pickup: state=ready→developing. On all GREEN all tickets: state=developing→developed + AUTO-HANDOFF /auditor (default, salvo defer_audit:true en checkpoint con razón documentada). REFUSE pickup nueva story si current worktree tiene story en state ∈ {developing, developed, reviewing} sin defer_audit. On cap reached: state=developing→blocked, escalate. Activa cuando user dice: '/dev-team', 'toma ticket T-N', 'implementa T-N', 'arranca build', 'autonomous build'.

Frontend specialist for Next.js 16 App Router + React 19 + Tailwind + Shadcn UI using Feature-Sliced Design Lite (domain-grouped features/, not traditional layers). Use when: creating responsive layouts, building interactive forms/dashboards, implementing dynamic routes, integrating Shadcn UI components, refactoring UI architecture, configuring Tailwind theming, wiring React Query hooks to backend APIs, or solving Server/Client Component boundaries. Triggers: 'nueva funcionalidad', 'modifica el front', 'crea un componente', 'refactoriza la UI', 'implementa layout', 'configura rutas', 'integra con la API', 'arregla el estilo'.

Git and GitHub workflow assistant for Nicolify (ap_sales_agent). Creates and manages branches, handles pull requests, resolves merge conflicts, generates changelogs, and manages releases and deployments. Use when the user asks to "create a branch", "sync with github", "push changes", "merge to main", "create a release", "make a PR", "resolve conflicts", "check git status", "deploy to production", "create a version", "write a changelog", or any git/GitHub related task. Also triggers on "quiero hacer un commit", "quiero pushear", "hacemos un release", "pasamos a producción", "nueva versión", "rama nueva".

Full production deployment pipeline: merge development to main, run /test-all fixing all errors, commit, push to trigger GitHub Actions, and monitor the workflow until deployment completes. Use when the user says "pase a producción", "hagamos un pase", "deploy to production", "pasamos a prod", "subamos a producción", or "vamos a producción".

Use this skill ANY time you write, debug, run, audit, extend, or even *think about* Playwright E2E tests in Nicolify. Activate when the user mentions: 'smoke test', 'e2e', 'playwright', 'tests E2E', 'agreguemos un smoke', 'el smoke falla', 'auth de Clerk en tests', 'test:e2e', 'spec.ts', 'storageState', 'auth.fixture', 'POM', 'page object', 'browser test', 'test integral', 'preflight', 'test que abra el navegador', 'verificar el flujo X end-to-end', 'CI de Playwright', 'fixtures de Playwright', '/test-all flake', 'playwright report', 'trace viewer', 'visual regression Playwright', 'verify project', 'Clerk testing token', 'CLERK_TESTING_TOKEN', 'playwright/.clerk/user.json', 'Bot traffic detected', 'Clerk Frontend API URL is required', 'session expired Playwright'. ALSO trigger proactively before any commit/PR that touches `frontend/e2e/**` or any UI flow that could affect smoke tests, and before any GH Actions change to `e2e-tests.yml`. Covers: Clerk auth lifecycle (testing token + storageState + freshness gate + retry + sanity check), Page Object Models, network mocking with `page.route`, multi-tenant fixture, sharding, flaky-test debugging via trace viewer, and Nicolify-specific anti-patterns (NEVER `make e2e*` Docker — crashes the laptop). When in doubt, USE this skill — under-triggering Playwright knowledge is the #1 cause of broken E2E suites in this codebase.

PM único del proyecto (single-brand) — owner del SSoT funcional. Pointer-first: carga docs/PROJECT-MAP.md + docs/product/checkpoint.md + docs/product/BACKLOG.md (si existe) en bootstrap. Owner: docs/product/{outcomes,stories,capabilities,modules}/, docs/learnings/, docs/architecture/, docs/domains/. Hereda paradigm v4 (10 estados macro) del método Luana. Auto-chain a /po-ux, /po, /ux-agentico, /architect, /dev-team, /auditor via Skill tool inline. Activa: '/pm', 'estado proyecto', 'backlog', 'story', 'outcome', 'capability', 'learning', 'refinemos X', 'qué hacemos hoy'.

Product Owner + UX/UI Designer fusión v4 (post pm-redesign 2026-05 Punto 4). Toma 1 UI standard story (CRUD/list/detail/form/dashboard) state=refining → produce 01-spec.md UNIFICADO con Gherkin AI-resistant + wireframes inline (ASCII / HTML mockup / Figma link) + estados visuales + microcopy Spanish neutro + Playwright graders → transition state=refining→refined al ratificar. NO se usa para agentic-stories (use /ux-agentico) ni service-stories (use /po). Loop iterativo Chris hasta ratificación. Activa cuando user dice: '/po-ux', 'definamos esta historia UI', 'spec + diseño', 'pantalla CRUD', 'dashboard', 'form nuevo', 'list view', 'detail page', 'wireframe', 'mockup'.

Audita un proyecto EXISTENTE (con código + docs) y produce un mapa navegable (PROJECT-MAP.md + MODULES-MATRIX.md + TECH-DEBT.md + STARTER-KIT-PLAN.md). Detecta stack, topología, módulos, capabilities, conventions. NO ejecuta /pm-bootstrap (greenfield). Use cuando Chris dice: '/project-audit', 'auditá el proyecto', 'mapeá esto', 'qué tenemos acá', 'analiza el repo', 'adopta este código al método Luana', 'baseline del proyecto'.

Entrevista profunda greenfield + decide stack (priorizando Luana: FastAPI + Next.js + Clerk + Postgres + Qdrant) + scaffold inicial + PROJECT-MAP. Para proyectos VACÍOS o casi vacíos. NO ejecutar en proyectos con código existente — usar /project-audit en su lugar. Activa cuando Chris dice: '/project-bootstrap', 'arrancamos proyecto nuevo', 'greenfield', 'desde cero', 'bootstrap proyecto', 'crear scaffold', 'iniciá proyecto'.

Senior + arquitecto + CTO del módulo sales_agent post redesign 2026-04. Carga §3 protected surfaces, anti-patterns, decisiones cross-fase, checklist pre-commit. NO carga code vivo (paths/LOC/tests cambian). Use cuando user pida cambio/feature/bug en sales_agent: voz de marca, scheduler/payment tools, observabilidad, callback handler, prompt cache, channel registry, semantic router, closer studio, follow_up engine, eval loop, costo agentes. Triggers: 'modifica sales_agent', 'bug en sales_agent', 'agregar tool al agente', 'agente no cierra', 'suena robótico', 'voz de marca', 'agregar canal sales', 'modificar prompt del specialist', 'closer studio', 'follow-up no dispara', 'el agente repite preguntas', 'PII en trazas', 'costo Kimi', 'DeepSeek alias', 'tier pricing 200k', 'eval goldens'.