Team AI Playbook — FinCore Customer Support Portal

Este repositorio contiene el Playbook de gobernanza del equipo para el engagement FinCore Customer Support Portal, el pipeline CI que verifica las reglas automáticamente, y los artifacts de atestación del proceso.

Estructura

team-ai-playbook/
├── 00-START-HERE.md             ← El ciclo completo, de la conversación a la entrega
├── documents/
│   ├── sample-client-discovery-meeting.md ← Conversación cliente–PM (punto de partida)
│   ├── 01-problem-validation.md ← Validación del problema (artefacto #1 del PM)
│   └── 02-requirements.md       ← Requisitos y decisiones (registro canónico D-/REQ-/AC)
├── 01-spec-standard.md          ← Criterios C1–C4 y convenciones de spec
├── 02-pipeline.md               ← Los 5 scripts, orden de ejecución, CI config
├── 03-qa-integration.md         ← Test library, revisión de AI output, escalación
├── 04-architecture-decisions.md ← ADRs activos
├── 05-engagement-assessment.md  ← FinCore Support Portal Tier 2 — Internal Only (T2)
├── 06-data-rules.md             ← NEVER / ALWAYS / WITH APPROVAL + patrones CI
├── 07-onboarding.md             ← Path 3 semanas + gate Month 1
├── gate-policy.json             ← Gates requeridos y sus owners
├── attestation/
│   └── gates.log                ← Log de atestación (generado por attest-gate.sh)
└── scripts/
    ├── validate-spec.sh         ← C1–C4 en specs (Spec Library Owner, QA)
    ├── check-design.sh          ← Secciones del design.md (ADR Owner, ARCH)
    ├── check-test-order.sh      ← Test-first order (QA Library Owner + DEV)
    ├── secret-scan.sh           ← Credenciales (+ capa data-governance) (DEV/SEC)
    ├── verify-gate.sh           ← Cada AC-NNN tiene ≥1 test (QA Library Owner)
    ├── attest-gate.sh           ← MECÁNICA: registro en el log (Pipeline Owner)
    ├── verify-attestation.sh    ← MECÁNICA: bloquea merge si faltan gates (Pipeline Owner)
    └── scan-patterns/
        ├── base-patterns.conf   ← Credenciales genéricas
        └── engagement-patterns.conf ← Patrones específicos del engagement

5 gates de calidad (required): validate-spec.sh, check-design.sh, check-test-order.sh, secret-scan.sh, verify-gate.sh. 2 piezas de mecánica (kind: mechanism): attest-gate.sh (registra) y verify-attestation.sh (bloquea el merge). Ver 02-pipeline.md y gate-policy.json.

Skills del repositorio SDD — Cómo se usan con este Playbook

Este Playbook define quién es responsable de qué, cuándo actuar, y qué verifica el CI. Las skills del repositorio SDD son las herramientas de AI que el equipo usa para generar los artifacts que el pipeline luego verifica. La relación es simple: las skills producen; el Playbook gobierna; el CI certifica.

Las skills están organizadas por la etapa del ciclo SDD en la que intervienen:

1. Descubrimiento y validación del problema

Antes de escribir una spec, estas skills extraen y estructuran la información del cliente:

Skill	Qué produce	Dónde entra en el Playbook
meeting-notes-extractor	Requisitos estructurados a partir de una conversación con el cliente	Input para la spec (Sección 1)
document-requirement-extractor	Requisitos a partir de documentos de negocio o contratos	Input para la spec (Sección 1)
codebase-requirement-extractor	Requisitos implícitos a partir del código existente	Input para la spec (Sección 1)
sdd-problem-validation	Validación de que el problema vale ser resuelto antes de invertir en una spec	Paso previo al pipeline
sdd-business-case	Justificación de negocio del trabajo	Contexto del PM para la Sección 5
sdd-stakeholder-register	Registro de stakeholders y sus intereses	Contexto del PM para la Sección 5

2. Generación y calidad de specs

Las specs que produce el equipo deben pasar validate-spec.sh (criterios C1–C4, Sección 1):

Skill	Qué produce	Dónde entra en el Playbook
generate-feature-specs	Spec completa en formato C1–C4	Verificada por validate-spec.sh
sdd-spec-quality-gate	Evaluación C1–C4 de una spec existente	Complementa validate-spec.sh
sdd-edge-case-generator	Acceptance criteria adicionales para casos de borde	Enriquece los criterios C2
sdd-out-of-scope-guard	Lista de lo que la spec explícitamente excluye	Sección Context de la spec
sdd-ux-spec-gate	Validación de specs que incluyen comportamiento de UI	Criterios C2 con Then observable
sdd-nfr-catalog	Catálogo de requerimientos no funcionales	Referenciados en ADR Reference (C4)
sdd-business-rule-catalog	Reglas de negocio que deben reflejarse en los criterios GWT	Criterios C2

3. Diseño y decisiones de arquitectura

Los artifacts de diseño alimentan la Sección 4 (ADRs) y son verificados por check-design.sh:

Skill	Qué produce	Dónde entra en el Playbook
sdd-design-architect	Design document con decisiones técnicas de la feature	Verificado por check-design.sh
sdd-adr-manager	ADRs en formato canónico con contexto, decisión y consecuencias	Sección 4 — Architecture Decisions
sdd-domain-modeler	Modelo de dominio (entidades, relaciones, invariantes)	Input para el design y los ADRs
sdd-api-contract-validator	Validación de contratos de API contra la spec	Complementa check-design.sh
sdd-threat-model	Análisis de amenazas y controles de seguridad	ADR de seguridad + Sección 6 (Data Rules)
sdd-traceability-matrix	Mapa requisito → spec → test → implementación	Soporte para C4 y auditoría
sdd-cross-feature-deps	Dependencias entre features que pueden afectar el diseño	Contexto del ADR

4. Build y orden test-first

El orden test-first es verificado por check-test-order.sh (Sección 3). Estas skills soportan el proceso:

Skill	Qué produce	Dónde entra en el Playbook
generate-tasks	Tasks de implementación derivadas de la spec y el design	Input para el DEV antes del build
sdd-test-first	Tests en estado Red derivados de los acceptance criteria	Verificados por check-test-order.sh
sdd-test-strategy	Estrategia de testing para la feature	Sección 3 — QA Integration
sdd-code-review	Revisión de código AI-generado	Protocolo de revisión (Sección 3)
sdd-stacked-changes	Gestión de PRs dependientes en el pipeline	Sección 2 — Pipeline
sdd-accessibility-audit	Auditoría de accesibilidad del output	Complementa los criterios de QA
sdd-performance-test	Tests de performance para NFRs definidos	Sección 3 — Test library

5. Seguridad y gobernanza de datos

Estas skills son el equivalente AI-asistido de los controles que secret-scan.sh verifica automáticamente (Secciones 5 y 6):

Skill	Qué produce	Dónde entra en el Playbook
sdd-secret-scan	Análisis de credenciales y datos sensibles en el código	Complementa secret-scan.sh
sdd-data-governance	Clasificación de datos del engagement y restricciones de uso	Secciones 5 y 6
sdd-compliance-mapper	Mapa de regulaciones aplicables al engagement	Justificación del Tier en Sección 5
sdd-prompt-sanitizer	Sanitización de prompts — elimina datos T1/T2 antes de enviarlos a APIs	Crítico para Tier 2 — Internal Only
sdd-rag-governance	Gobernanza de datos usados en RAG pipelines	Sección 6 — Data Rules para AI retrieval
sdd-context-injection	Gestión segura del contexto inyectado en prompts	Patrones en engagement-patterns.conf
sdd-supply-chain	Seguridad de la cadena de suministro de dependencias	Sección 4 (ADR de dependencias)

6. Verificación de gates

La fase de verificación comprueba que la implementación satisface los acceptance criteria:

Skill	Qué produce	Dónde entra en el Playbook
sdd-verify-gate	Verificación de que cada AC-NNN tiene al menos un test	Verificado por verify-gate.sh
sdd-ai-evaluation	Evaluación de outputs de AI contra criterios de calidad	Protocolo de revisión (Sección 3)
sdd-chaos-engineering	Tests de resiliencia bajo condiciones adversas	Sección 3 — QA Integration avanzada
sdd-agent-observability	Observabilidad de los agents de AI en el pipeline	Sección 4 (ADR de observabilidad)

7. Release, operaciones y cierre

Estas skills gestionan la segunda mitad del ciclo SDD — desde el merge aprobado hasta el handoff:

Skill	Qué produce	Dónde entra en el Playbook
sdd-release-rollout	Plan de rollout con gates de release y criterios de rollback	Sección 2 — Pipeline (back of cycle)
sdd-rollback-rehearsal	Ensayo documentado del procedimiento de rollback	Sección 2 — obligatorio para Tier 2
sdd-deployment-safety	Checklist de seguridad de despliegue	Complementa verify-attestation.sh
sdd-pm-handoff	Documento de handoff al PM con el sistema operativo	Entregable final del ciclo
sdd-slo-runbook	Runbooks de SLO para operación continua	Sección 4 (ADR de operaciones)
sdd-dr-plan	Plan de recuperación ante desastres	Sección 4 (ADR de continuidad)
sdd-incident-postmortem	Postmortem estructurado de incidentes	Trigger para updates de Sección 6

8. Gestión del conocimiento y planificación

Skills de soporte que alimentan la gobernanza a largo plazo del Playbook:

Skill	Qué produce	Dónde entra en el Playbook
sdd-glossary-governance	Glosario de términos del dominio y del engagement	Vocabulario compartido en Sección 1
sdd-knowledge-management	Estructura de conocimiento del equipo para onboarding	Sección 7 — Onboarding
sdd-tech-debt-register	Registro de deuda técnica con impacto y plan de resolución	Sección 4 (ADRs de deuda técnica)
sdd-roadmap	Roadmap priorizado de features y capacidades	Contexto del PM para la Sección 5
sdd-capacity-planning	Estimación de capacidad del equipo para el ciclo	Contexto del PM para el sprint

---

Resumen: Las skills producen los artifacts (specs, designs, ADRs, tests, runbooks). Este Playbook define las reglas que esos artifacts deben cumplir. El pipeline CI verifica automáticamente las reglas en cada commit. La gobernanza de la Semana 12 cierra el ciclo: asigna a personas reales la responsabilidad de mantener tanto las reglas como las skills actualizadas cuando el sistema evoluciona.

Roles de Gobernanza

Sección	Owner	Trigger
01 — Spec Standard	Spec Library Owner (QA)	Patrón de falla no cubierto en C1–C4
02 — Pipeline	Pipeline Owner (DEV)	Cambio en cualquier gate o pieza de mecánica
03 — QA Integration	QA Library Owner (QA)	Nueva categoría de tests o caso no documentado
04 — Architecture Decisions	ADR Owner (ARCH)	Nueva decisión técnica o ADR obsoleto
05 — Engagement Assessment	Assessment Owner (PM)	Cambio de scope o solicitud de reclasificación
06 — Data Rules	Assessment Owner (PM)	Nuevo tipo de dato o patrón no detectado
07 — Onboarding	Onboarding Owner (PM)	Nuevo integrante reporta laguna

Correr el pipeline localmente

# Pre-requisito: tener al menos un commit en el repositorio
git add specs/mi-feature.md
git commit -m "feat: add spec for [feature]"

# Correr los gates de calidad en orden
bash scripts/validate-spec.sh
bash scripts/check-design.sh
bash scripts/check-test-order.sh
bash scripts/secret-scan.sh
bash scripts/verify-gate.sh specs tests
# Mecánica: registrar cada gate y luego hacer cumplir la política
bash scripts/attest-gate.sh validate PASS
bash scripts/verify-attestation.sh

Gate de Month 1 (onboarding)

Verificar que un nuevo integrante completó un ciclo attestado:

EMAIL="nuevo@equipo.com"
grep "$EMAIL" attestation/gates.log | grep "RESULT=PASS" | wc -l
# Debe cubrir los gates requeridos de un ciclo completo (ver gate-policy.json)

---

Notas de fidelidad al framework (crosswalk)

Este playbook es una instanciación simplificada de un solo engagement (FinCore, Tier 2). Para mapear de vuelta al framework canónico (detailed_workflow_es.md, scripts/attestation/gate-policy.json, Skills/sdd-*):

• Ciclo completo. El pipeline cubre el frente (cliente → spec → diseño → build → verificación) con gates reales: validate (sdd-spec-quality-gate), design (sdd-design-architect), test-order (sdd-test-first), secret-scan (sdd-secret-scan), verify-gate (sdd-verify-gate). La mitad de entrega (release, ensayo de rollback, handoff) está descrita en gate-policy.json → back_of_cycle y la liderará SRE + PM (sdd-release-rollout, sdd-rollback-rehearsal, sdd-pm-handoff); para Tier 2/T2 financiero, rollback ensayado y handoff son obligatorios.
• Gates vs. mecánica. attest (registrador de evidencia) y attestation-check (bloqueo de merge) son mecánica del pipeline, no gates de calidad (kind: mechanism en la política). El contrato que bloquea el merge es verify-attestation.sh + gate-policy.json.
• Roles. Los 6 dueños de gobernanza mapean a los 7 roles del framework: Spec Library Owner→QA; Pipeline Owner→DEV; QA Library Owner→QA; ADR Owner→ARCH (posee el gate design); Onboarding Owner→cualquiera; Engagement Assessment Owner→PM. En este equipo pequeño, SEC (threat-model/data-governance/compliance) y SRE (release/rollback/SLO) son sombreros que llevan PM/DEV; en un equipo mayor se nombran por separado.
• Datos vs. credenciales. secret-scan.sh mezcla, por simplicidad del lab, credenciales (secret-scan) y clasificación de datos (que en el framework es sdd-data-governance). Ver encabezado del script.
• Atestación. El log usa KEY=VALUE legible; el framework real liga cada atestación a un hash del cambio (evidencia anti-manipulación). No editar gates.log a mano.
• Fases OpenSpec. El campo phase de cada gate corresponde a las fases /opsx: spec/design → propose/continue; build/verify → apply/verify; entrega → archive.