🎯 Scope — Control de Alcance

Objetivo: Eliminar la ambigüedad sobre cuándo una tarea está realmente terminada.

Los agentes de IA declaran victoria demasiado temprano. Sin un DoD explícito, el agente puede decir "listo" cuando solo escribió el código pero no verificó nada. El Definition of Done es un checklist que debe cumplirse antes de marcar una tarea como completada.

Estructura mínima:

• Código escrito según spec
• Tests pasan (pytest, cargo test, npm test)
• Sin regresiones visuales ni funcionales
• Documentado en README o docs/ si aplica
• Comiteado con mensaje descriptivo
• Sin secrets hardcodeados

Ejemplo en AGENTS.md:

## Definition of Done
- [ ] Código implementado y revisado
- [ ] Tests pasan: `python3 -m pytest`
- [ ] Sin errores de lint: `ruff check .`
- [ ] Documentación actualizada
- [ ] Commit con prefijo convencional (feat:/fix:/docs:)

Tip: El DoD debe estar en el briefing principal (AGENTS.md o CLAUDE.md) para que el agente lo vea en cada sesión.

Objetivo: Dividir el trabajo en hitos medibles con progreso explícito.

Un agente sin hitos claros tiende a saltar entre tareas o perderse en detalles. El TASK.md es el tablero de trabajo vivo. Debe contener:

• Milestone actual con nombre y fecha objetivo
• En progreso — lo que el agente está haciendo ahora
• Pendiente — próximas tareas priorizadas
• Completado — tareas cerradas con check
• Progreso porcentual — ej. "Fase 1: 80%"

Ejemplo de TASK.md:

## 🎯 Milestone: Fundación (Fase 1)

### En Progreso
- [ ] Contenido instructivo para cada subsistema

### Pendiente
- [ ] Integrar harness evaluador en la web
- [ ] Test suite: HTML validation + link checker

### Completado
- [x] Estructura base del sitio
- [x] Linear Dark design system

El ROADMAP.md complementa con la visión de largo plazo: fases, objetivos estratégicos y dependencias entre hitos.

Objetivo: Definir qué tipo de cambios son aceptables y cuáles no.

El CONTRIBUTING.md no es solo para humanos: le dice al agente qué puede y qué no puede hacer. Un buen CONTRIBUTING.md incluye:

• Alcance aceptable — tipos de contribuciones válidas
• Proceso — issue → branch → PR → review
• Estándares — HTML semántico, CSS sin !important, JS vanilla
• Una feature por PR — evita el scope creep

Ejemplo:

## Alcance
Aceptamos contribuciones que:
- Mejoren el contenido educativo del curso
- Optimicen el evaluador (nuevos checks)
- Mantengan compatibilidad: HTML/CSS/JS vanilla

## Estándares
- HTML semántico, accesible (aria-labels)
- CSS utility-first + componentes, sin !important
- JS vanilla en shared.js, sin dependencias externas
- Sin secrets hardcodeados

Objetivo: Darle al agente contexto sobre para quién trabaja.

Sin un perfil de usuario, el agente toma decisiones de diseño que pueden no alinearse con las preferencias reales. USER.md debe incluir:

• Identidad — nombre, handle, rol
• Preferencias de comunicación — idioma, estilo (directo vs. analítico)
• Restricciones — qué NO hacer (ej. no publicar proyectos privados)
• Proyectos relacionados — contexto de otros repos

Ejemplo:

## Quién es
Brahyan Belalcazar (ElBeRi) — creador de PGHEART

## Preferencias
- Idioma: español
- Estilo: acción directa, nada de análisis extenso
- Token-saving: información compacta

## Lo que NO quiere
- ❌ Proyectos privados en sitios públicos
- ❌ Verbose analysis de 400K tokens

Objetivo: Estandarizar la forma en que se reportan bugs y proponen cambios.

Las plantillas en .github/ISSUE_TEMPLATE/ y .github/PULL_REQUEST_TEMPLATE.md fuerzan al agente (y a humanos) a proporcionar la información necesaria antes de actuar.

Checks del evaluador:

• ¿Existen plantillas en .github/?
• ¿Incluyen campos obligatorios (descripción, pasos de reproducción)?

Estructura recomendada:

.github/
├── ISSUE_TEMPLATE/
│   ├── bug_report.md
│   └── feature_request.md
└── PULL_REQUEST_TEMPLATE.md

Tip: Incluso en proyectos personales, las plantillas ayudan al agente a no olvidar pasos importantes.

Antes de declarar una tarea completada, el agente debe verificar:

• ¿Existe un Definition of Done en AGENTS.md o RULES.md?
• ¿El TASK.md tiene milestones y progreso porcentual?
• ¿Existe CONTRIBUTING.md con alcance definido?
• ¿Existe USER.md con preferencias del usuario?
• ¿Hay plantillas en .github/ para issues y PRs?
• ¿Existe un backlog de tareas descubiertas?
• ¿El scope de esta sesión está limitado a una feature?

Score objetivo del subsistema Scope: ≥ 80% en harness scan . --json