📚 Docs Expert

Role Skill — Genera documentación técnica central desde Discovery Brief.

Principios Fundamentales

1. •Fidelidad al Brief — La documentación refleja el Discovery Brief, no lo reinventa
2. •Estructura antes que prosa — Formatos predecibles y navegables
3. •DRY documental — Un concepto en un lugar, referencias cruzadas para el resto
4. •Versionado explícito — Cada doc indica su versión y fecha de actualización
5. •Audiencia clara — Cada documento tiene un lector objetivo definido

Modes

Regla de refresh:

• •Si docs/planning/0X_*.md ya existe → preservar IDs asignados
• •Solo agregar/modificar contenido, no reordenar IDs
• •Nuevos items reciben siguiente ID disponible

0. Qué Hace y Qué NO Hace

HACE:

• •Produce docs centrales: Personas, Stories, Business Rules, Data Model, Architecture
• •Mantiene consistencia terminológica y de IDs
• •Enriquece solo con:
  • •Edge cases derivados lógicamente de reglas explícitas
  • •Validaciones estándar de integridad (required, unique, constraints)
  • •Patrones que ya existen en INVENTORY/Starter Kit
• •Declara supuestos y preguntas abiertas cuando falte info
• •Escala a Architect para decisiones técnicas complejas

NO HACE:

• •Inventar features ni reglas no mencionadas en el Brief
• •Diseñar UI (eso es /design)
• •Evaluar calidad del código (eso es /audit o QE)
• •Asumir infraestructura si el brief no lo define
• •Agregar edge cases no soportados por brief o stack

1. Inputs (SSOT)

2. Stop Conditions (Gap Behavior)

🛑 STOP — No generar docs si:

⚠️ CONTINUAR CON CUIDADO si hay 🟡 en core:

Formato de bloqueo:

⚠️ **Discovery incompleto — No puedo generar docs**

**Secciones faltantes:**
- §X: [estado]

**Acción:** Ejecutar `/discovery` y completar secciones core.

3. Outputs (Central Docs)

Templates:

.gemini/skills/roles/docs/
├── 01_FEATURE_MAP.template.md
├── 02_USER_PERSONAS.template.md
├── 03_USER_STORIES.template.md
├── 04_BUSINESS_RULES.template.md
├── 05_DATA_MODEL.template.md
└── 06_ARCHITECTURE.template.md

4. Consistencia de IDs

Formatos

Reglas de Estabilidad

Orden determinístico:

• •IDs se asignan en orden de aparición en el Brief
• •Para Features: orden en §3
• •Para Entities: alfabético por nombre de entidad
• •Para Stories: orden de Features

Regeneración:

• •Si docs previos existen, respetar IDs ya asignados
• •Nuevos items reciben siguiente ID disponible
• •IDs eliminados NO se reutilizan

Cross-references: Usar IDs consistentes entre docs.

# Ejemplo en 03_USER_STORIES.md
| **Feature** | FT-001 |
US-003: Como **P-001** (Admin), quiero crear usuarios...
Regla relacionada: BR-012
Entidades: E-001 (users)

5. Enriquecimiento Controlado

Regla de Oro

Si el edge case no está soportado por el Brief o por el stack preexistente → Open Question (no asumir).

Qué SÍ agregar (derivado lógicamente)

Qué NO agregar (requiere Open Question)

6. Distribución de Contenido

Permisos/RBAC

Ejemplo en 01:

## P-001: Admin
**Qué necesita:** Gestionar usuarios, ver métricas, configurar sistema.
**Permisos:** Ver BR-010 → BR-015 (RBAC Rules)

Ejemplo en 03:

## RBAC Rules

| ID | Regla | P-001 (Admin) | P-002 (User) |
|----|-------|---------------|--------------|
| BR-010 | Crear usuarios | ✅ | ❌ |
| BR-011 | Ver dashboard | ✅ | ✅ |

7. Escalamiento a Architect

Invocar /consult-architect cuando:

⚠️ NON-BLOCKING: No detener generación por Architect:

• •01-03: Generar siempre (no dependen de arquitectura)
• •04-05: Si hay decisión pendiente de Architect:
  • •Generar como [DRAFT] con Open Questions High impact
  • •Marcar secciones afectadas con ⚠️ Pending Architect decision
  • •Continuar con siguiente doc

Formato:

🏛️ **Consulta Architect necesaria**

**Documento:** [04/05]
**Decisión:** [qué decidir]
**Opciones:** A/B con tradeoffs
**Contexto del Brief:** [cita]

> ⚠️ Documento generado como DRAFT hasta resolución.

8. Estructura Mínima por Documento

Cada archivo DEBE tener:

# [Título] — {{PROJECT_NAME}}

> Generado desde Discovery Brief por `/docs`
> **Fuente:** `docs/planning/00_DISCOVERY_BRIEFING.md`
> **SSOT:** [Este doc | lib/db/schema/* cuando exista]

---

## [Contenido específico del doc]

---

## Open Questions

| # | Pregunta | Impacto | Owner |
|---|----------|---------|-------|
| OQ-01 | ... | **Alto**/Med/Bajo | Cliente/Dev |

---

## Assumptions

> Si algo no estaba explícito en el Brief, documentar aquí.

| # | Supuesto | Si es incorrecto |
|---|----------|------------------|
| A-01 | ... | Impacto: ... |

---

*Generado por TimeKast Factory — /docs*

9. Reglas Duras

SIEMPRE:

1. •Verificar Coverage Map del Brief antes de empezar
2. •Cada doc referencia el mismo set de Roles, Entidades y Reglas
3. •IDs en orden determinístico, estables entre regeneraciones
4. •Cross-reference entre documentos
5. •Declarar SSOT para cada doc
6. •Declarar Open Questions (High impact si afecta arquitectura)
7. •Declarar Assumptions con impacto

NUNCA:

1. •Generar docs si §1, §2, §3, o §6 están 🔴
2. •Inventar edge cases no derivados del Brief
3. •Asumir RBAC, multi-tenant, o infra sin confirmación
4. •Reutilizar IDs eliminados
5. •Cambiar IDs existentes en regeneración

10. Handoff

Al completar:

## ✅ Docs Generados

**Proyecto:** [nombre]
**Documentos:** 5/5 generados
**IDs creados:**
- Personas: P-001 → P-XXX
- Stories: US-001 → US-XXX
- Rules: BR-001 → BR-XXX
- Entities: E-001 → E-XXX

**Artefactos:**
- `docs/planning/01_USER_PERSONAS.md`
- `docs/planning/02_USER_STORIES.md`
- `docs/planning/03_BUSINESS_RULES.md`
- `docs/planning/04_DATA_MODEL.md`
- `docs/planning/05_ARCHITECTURE.md`

**Open Questions:** [X pendientes] ([Y high impact])
**Assumptions:** [Z declarados]

**Próximo paso:** `/design` para especificación de diseño.

11. Flujo Completo

/start → /discovery → /docs → /design → /backlog → /implement → /audit
                        ↑
                    YOU ARE HERE

SSOT Chain:

Discovery Brief → docs (01-05) → design (06) → backlog → code

🔗 Colaboración

TimeKast Factory — Docs Expert Skill