diff --git a/.agents/rules/ai-feedback-learning-loop.md b/.agents/rules/ai-feedback-learning-loop.md new file mode 100644 index 0000000000..877d870e94 --- /dev/null +++ b/.agents/rules/ai-feedback-learning-loop.md @@ -0,0 +1,50 @@ +# AI Feedback Learning Loop + +> Documents the process for AI agents to propose rule changes and await human approval. Prevents silent rule drift between sessions. + +## When to Propose a Change + +Propose a rule change when any of the following happen: + +- A human corrects your approach during development and the correction is worth preserving project-wide +- You discover a pattern, constraint, or convention that recurs across multiple tasks and is not yet captured in `.agents/rules/` +- A tool, command, or workflow behaves differently than what the rules describe +- An accepted convention turns out to be incorrect or outdated + +Do not propose a change for one-off situations specific to a single task. + +## Proposal Format + +When you identify a change worth proposing, output the following block in your response: + +``` +## Rule Change Proposal + +**Triggered by**: [What correction or learning surfaced this] +**Proposed rule**: [Exact text to add/change/remove in base.md] +**Section**: [Which section of base.md this belongs in] +**Rationale**: [Why this is worth preserving project-wide] + +Awaiting human approval before applying. +``` + +Include this block in-line in your response — do not create a file or modify any `.agents/rules/` file until the human explicitly approves. + +## One-at-a-Time Constraint + +Only propose one rule change per session. If multiple corrections surface, log them in `specs//lessons-learned.md` and propose them one at a time in future sessions after the current proposal is resolved. + +## Human Approval Required + +AI agents MUST NOT self-apply rule changes. The rule files in `.agents/rules/` are governance documents — changes require human review and explicit approval. This prevents agents from silently shifting project conventions based on in-session learning that may be wrong or context-specific. + +Approval means the human explicitly says something like "approved", "apply it", or "go ahead and update base.md". Implicit agreement or lack of objection is not approval. + +## How to Apply After Approval + +Once a human explicitly approves a rule change: + +1. Open `.agents/rules/base.md` (or the relevant rule file) +2. Apply the exact change described in the proposal — no scope creep +3. Open a PR with the change; include `Rule-Change-Approval: ` in the PR description (reference the conversation, issue, or comment where approval was given) +4. CI will verify the approval reference is present before allowing the merge diff --git a/.agents/rules/base.md b/.agents/rules/base.md new file mode 100644 index 0000000000..5922c297cb --- /dev/null +++ b/.agents/rules/base.md @@ -0,0 +1,157 @@ +# Base Agent Rules + +> Single source of truth for AI agent conventions in this project. Read this file at the start of every session before doing anything else. + +## Project Overview + +This is a full-stack web application with a Python backend and TypeScript/Node 22 frontend. + +**Backend**: Python 3.10+, FastAPI, SQLModel, PostgreSQL, managed with `uv` +**Frontend**: TypeScript, Node 22, ESM-only, managed with `bun` +**CI/CD**: GitHub Actions — automated tests, linting, Docker compose validation, Claude AI review +**Infrastructure**: Docker Compose for local development and CI + +Architecture: HTTP API (backend) consumed by a single-page frontend. Services run in Docker containers locally and in staging/production via GitHub Actions deployments. + +``` +full-stack-agentic/ + backend/ Python FastAPI application + frontend/ TypeScript/Node 22 frontend + .github/ CI workflows, PR templates, CODEOWNERS + .agents/rules/ AI agent conventions (this directory) + .claude/ Claude Code settings and commands + specs/ Feature specifications (SpecKit artifacts) +``` + +## Project Structure + +``` +. +├── backend/ +│ ├── app/ Application source (routers, models, services) +│ ├── tests/ pytest test suite +│ └── pyproject.toml +├── frontend/ +│ ├── src/ TypeScript source +│ └── package.json +├── .github/ +│ ├── workflows/ CI workflow files +│ ├── CODEOWNERS Auto-review assignments +│ └── pull_request_template.md +├── .agents/ +│ └── rules/ Agent rule files (base.md, coding-standards.md, ai-feedback-learning-loop.md) +├── .claude/ +│ ├── commands/ SpecKit skill files +│ └── settings.json Shared Claude tool permissions +└── specs/ Per-feature SpecKit artifacts +``` + +## Available Commands + +### Backend Tests + +```bash +uv run pytest +``` + +```bash +uv run python -m pytest +``` + +### Backend Lint + +```bash +uv run ruff check . +``` + +```bash +uv run ruff format . +``` + +### Backend Type Check + +```bash +uv run ty check +``` + +### Frontend Tests + +```bash +bun run test +``` + +### Frontend Lint + +```bash +bun run lint +``` + +### Docker (local dev) + +```bash +docker compose up +``` + +```bash +docker compose down +``` + +### SpecKit Scripts + +```bash +.specify/scripts/bash/ +``` + +## Testing Conventions + +- Backend tests live in `backend/tests/`, mirroring the `app/` package structure +- Run with `uv run pytest` from the repo root or `backend/` directory +- Frontend tests are colocated (`*.test.ts`) alongside source files +- Run with `bun run test` from `frontend/` +- Test behavior, not implementation — tests verify what code does, not how +- Mock only boundaries: network, filesystem, external services +- Every error path the code handles should have a test + +## SpecKit Workflow + +This project uses SpecKit for structured feature development. The phases are: +`/speckit.specify` → `/speckit.clarify` → `/speckit.plan` → `/speckit.tasks` → `/speckit.implement` + +Artifacts live in `specs/-/`. + +### Retro Gate (mandatory) + +After every SpecKit phase command completes (`/speckit.specify`, `/speckit.plan`, +`/speckit.tasks`, `/speckit.implement`), run `/speckit.retro` before starting +the next phase. Do not proceed until the retro produces a "Ready" status. + +**Micro-retro** (after each task in `/speckit.implement`): +1. Simplify the code just written +2. Log anything unexpected to `specs//lessons-learned.md` +3. Check whether `tasks.md`, `plan.md`, or `spec.md` needs updating +4. Suggest `/clear` before the next task + +**Phase retro** (after each phase command): +1. Summarize what was produced +2. Review `lessons-learned.md` +3. Check all earlier artifacts for drift +4. Propose constitution/rules updates (never self-apply — await human approval) +5. Confirm readiness gate (5 items) +6. Suggest `/clear` with specific files to re-read + +## Rule Proposal Process + +When you receive a correction or discover a pattern worth preserving project-wide, propose a rule change following the process in `.agents/rules/ai-feedback-learning-loop.md`. + +Key constraint: **never self-apply rule changes**. Always propose and wait for explicit human approval before modifying any file in `.agents/rules/`. + +## SDD Development Workflow + +1. **Branch**: Create a feature branch from `master` — `git checkout -b -` +2. **Develop**: Implement the feature; run tests and linter locally before committing +3. **PR**: Open a pull request against `master` using the PR template in `.github/pull_request_template.md` +4. **CI**: GitHub Actions runs tests, lint, and automated Claude code review +5. **Review**: CODEOWNERS auto-requests designated reviewers for affected paths +6. **Merge**: Merge after CI passes and reviewers approve — no direct pushes to `master` + +Changes to `.agents/rules/base.md` require a `Rule-Change-Approval: ` line in the PR description. CI will block the PR if absent. diff --git a/.agents/rules/coding-standards.md b/.agents/rules/coding-standards.md new file mode 100644 index 0000000000..e840b36977 --- /dev/null +++ b/.agents/rules/coding-standards.md @@ -0,0 +1,82 @@ +# Coding Standards + +> Agreed-upon code quality standards for AI agents to apply consistently across this project. + +## Python Standards + +**Runtime**: Python 3.10+, managed with `uv` + +**Linting and formatting**: `ruff` — run `uv run ruff check .` and `uv run ruff format .` +**Type checking**: `ty` — run `uv run ty check` + +**Naming**: +- Modules, functions, variables: `snake_case` +- Classes: `PascalCase` +- Constants: `UPPER_SNAKE_CASE` + +**Type annotations**: Required on all non-trivial public functions and methods. Use `from __future__ import annotations` for forward references. + +**Import order** (enforced by ruff): +1. Standard library +2. Third-party packages +3. Local application imports + +No relative imports (`..`) — use absolute imports only. + +**Function size**: Max 100 lines, cyclomatic complexity ≤ 8, max 5 positional parameters. + +**Docstrings**: Google-style on non-trivial public APIs. Code should be self-documenting — only add docstrings where the purpose isn't obvious from names and types. + +## TypeScript Standards + +**Runtime**: Node 22, ESM-only (`"type": "module"` in package.json) +**Package manager**: `bun` + +**Linting and formatting**: `oxlint` and `oxfmt` + +**tsconfig.json** — enable all strictness flags: +- `strict: true` +- `noUncheckedIndexedAccess: true` +- `exactOptionalPropertyTypes: true` +- `noImplicitOverride: true` +- `noPropertyAccessFromIndexSignature: true` +- `verbatimModuleSyntax: true` +- `isolatedModules: true` + +**Naming**: +- Variables, functions: `camelCase` +- Classes, types, interfaces: `PascalCase` +- Constants: `UPPER_SNAKE_CASE` +- Files: `kebab-case.ts` + +No relative imports (`../`) across package boundaries — use absolute imports configured via `tsconfig.json` paths. + +**Test files**: Colocated as `*.test.ts` alongside source files. + +## Testing Principles + +**Test behavior, not implementation.** Tests verify what the code does, not how. A refactor that doesn't change behavior must not break tests. + +**Test edges and errors, not just the happy path.** Empty inputs, boundary values, malformed data, missing files — bugs live in edges. Every error path the code handles should have a test that triggers it. + +**Mock only boundaries.** Mock things that are slow (network, filesystem), non-deterministic (time, randomness), or external services you don't control. Never mock internal application logic. + +**Verify tests catch failures.** Break the code, confirm the test fails, then fix. Tests that always pass regardless of implementation are useless. + +## Error Handling + +**Fail fast with clear, actionable messages.** When something goes wrong, raise immediately with context: what operation failed, what input caused it, and what the caller should do. + +**Never swallow exceptions silently.** No bare `except: pass` or `.catch(() => {})`. If an error is genuinely ignorable, add a comment explaining why. + +**Include context in error messages**: what operation was attempted, what the unexpected value was, and a suggested fix where possible. + +## Comments + +**Code should be self-documenting.** Choose names that make the purpose obvious. If a comment explains what the code does, the code probably needs refactoring. + +**No commented-out code.** Delete it. Version control exists to recover deleted code. + +**Comments explain why, not what.** The only valid use for a comment is to explain a non-obvious decision, a known limitation, or a gotcha that the code cannot express. + +**No `` comments in rule files.** Open items go to `tasks.md`. diff --git a/.claude/commands/checklist.md b/.claude/commands/checklist.md new file mode 100644 index 0000000000..37cfed0650 --- /dev/null +++ b/.claude/commands/checklist.md @@ -0,0 +1,85 @@ +--- +description: "OPCIONAL — Valida la calidad de los requirements antes de implementar. Puede ejecutarse en cualquier momento." +--- + +## Propósito + +Genera un checklist que valida que el spec, el plan y las tareas están bien escritos, son completos y no tienen ambigüedades. No bloquea el flujo — es una herramienta de calidad opcional. + +Recuerda: el checklist valida los **requirements**, no el código. Es un "test unitario del spec escrito en inglés". + +--- + +## Ejecución + +### 1. Verificar rama y PR + +```bash +git branch --show-current +gh pr view --json number,state,url,body +``` + +- Si la rama es `main` o `master`: ERROR "No estás en una rama de feature. Ejecuta /status." +- Si no hay PR: ERROR "No hay PR abierto. ¿Ejecutaste /start?" + +### 2. Verificar que hay algo que revisar + +Confirmar que existe al menos `spec.md` en el directorio de la feature. + +```bash +ls specs// +``` + +Si no hay spec: ERROR "No hay spec para revisar. Ejecuta /start primero." + +### 3. Delegar en speckit.checklist + +Invocar `/speckit.checklist` con el contexto de la fase actual. + +`speckit.checklist` se encarga de: +- Detectar qué artefactos están disponibles (spec, plan, tasks) +- Hacer preguntas de clarificación sobre el enfoque del checklist +- Generar el fichero en `specs//checklists/.md` +- Validar completeness, clarity, consistency, measurability, coverage + +**Esperar a que `speckit.checklist` termine completamente antes de continuar.** + +### 4. Commit del checklist + +```bash +git add specs/ +git commit -m "docs: añadir checklist de requirements" +git push origin HEAD +``` + +### 5. Informe final + +``` +✅ Checklist generado + +📋 + +Revisa los items marcados como [Gap], [Ambiguity] +o [Conflict] antes de continuar con /implement. + +───────────────────────────────────────── +➡️ SIGUIENTE PASO +───────────────────────────────────────── +Cuando estés listo para implementar: + /implement +───────────────────────────────────────── +``` + +### Cierre de sesión + +Leer el contexto actual de la sesión (igual que `/context`). + +- **🟢 / 🟡**: No mostrar nada. +- **🟠**: Mostrar al final del informe: + ``` + 🟠 El contexto está alto. Abre una sesión nueva antes del siguiente comando. + ``` +- **🔴**: Mostrar antes del informe final e interrumpir si el usuario intenta continuar: + ``` + 🔴 Contexto crítico. Abre una sesión nueva AHORA antes de continuar. + ``` diff --git a/.claude/commands/consolidate-spec.md b/.claude/commands/consolidate-spec.md new file mode 100644 index 0000000000..5315bdfa5e --- /dev/null +++ b/.claude/commands/consolidate-spec.md @@ -0,0 +1,91 @@ +--- +description: "PASO 2 — Integra el feedback del equipo en el spec. Ejecutar después de que hayan comentado en el PR. Repetible." +--- + +## Ejecución + +### 1. Verificar rama y PR + +```bash +git branch --show-current +gh pr view --json number,state,url,body +``` + +- Si la rama es `main` o `master`: ERROR "No estás en una rama de feature. Ejecuta /status." +- Si no hay PR: ERROR "No hay PR abierto. ¿Ejecutaste /start?" + +### 2. Gate: spec creado + +Verificar en el body del PR: `- [x] Spec creado` + +Si no está marcado: ERROR "El spec no existe todavía. Ejecuta /start primero." + +### 3. Verificar que hay comentarios + +```bash +gh pr view --json comments -q '.comments[].body' +``` + +Si no hay comentarios: ERROR "No hay comentarios en el PR todavía. Comparte el PR con el equipo y espera su feedback." + +### 4. Delegar en speckit.clarify + +Invocar `/speckit.clarify` con el contexto de los comentarios del PR. + +`speckit.clarify` se encarga de: +- Leer el spec actual +- Procesar las clarificaciones necesarias +- Actualizar `spec.md` con las decisiones tomadas + +**Esperar a que `speckit.clarify` termine completamente antes de continuar.** +Si produce ERROR: propagar y parar. + +### 5. Commit del spec actualizado + +```bash +git add specs/ +git commit -m "docs: actualizar spec con feedback del equipo" +git push origin HEAD +``` + +### 6. Actualizar historial del PR + +Añadir fila a la tabla: +``` +| Spec revisado | YYYY-MM-DD | Feedback integrado vía speckit.clarify | +``` + +```bash +gh pr edit --body "" +``` + +### 7. Informe final + +``` +✅ Spec actualizado + +───────────────────────────────────────── +➡️ SIGUIENTE PASO +───────────────────────────────────────── +Si hay más rondas de feedback: + Vuelve a ejecutar /consolidate-spec + +Si el spec está listo para aprobación: + Pide al equipo que apruebe el spec en el PR. + Cuando lo hagan, ejecuta: /plan +───────────────────────────────────────── +``` + +### Cierre de sesión + +Leer el contexto actual de la sesión (igual que `/context`). + +- **🟢 / 🟡**: No mostrar nada. +- **🟠**: Mostrar al final del informe: + ``` + 🟠 El contexto está alto. Abre una sesión nueva antes del siguiente comando. + ``` +- **🔴**: Mostrar antes del informe final e interrumpir si el usuario intenta continuar: + ``` + 🔴 Contexto crítico. Abre una sesión nueva AHORA antes de continuar. + ``` diff --git a/.claude/commands/context.md b/.claude/commands/context.md new file mode 100644 index 0000000000..4f33980a7c --- /dev/null +++ b/.claude/commands/context.md @@ -0,0 +1,39 @@ +--- +description: "UTILIDAD — Muestra cuánta memoria le queda a Claude en esta sesión." +--- + +## Ejecución + +### 1. Leer contexto real de la sesión + +```bash +ls -t ~/.claude/sessions/ 2>/dev/null | head -1 +``` + +Leer `remaining_percentage` o calcular desde `used_tokens` / `total_tokens`. +Si no se puede leer: usar estimación conservadora basada en la longitud de la conversación. + +### 2. Determinar nivel + +| % usado | Nivel | Emoji | +|---------|-------|-------| +| < 50% | Puedes continuar | 🟢 | +| 50–79% | Termina el paso actual | 🟡 | +| 80–89% | Abre sesión nueva pronto | 🟠 | +| ≥ 90% | Abre sesión nueva YA | 🔴 | + +### 3. Mostrar informe + +Mostrar SOLO el nivel actual, la barra y la recomendación correspondiente. Ejemplo para 🟠: + +``` +[████████████████░░░░] 83% usado + +🟠 Abre sesión nueva pronto +``` + +La recomendación es obligatoria y se muestra siempre debajo de la barra. + +### 4. Mostrar siguiente paso + +Mostrar el siguiente paso pendiente del flujo (igual que `/status`) para que al abrir sesión nueva el usuario sepa qué ejecutar. diff --git a/.claude/commands/deploy-to-stage.md b/.claude/commands/deploy-to-stage.md new file mode 100644 index 0000000000..0cc7d8ef06 --- /dev/null +++ b/.claude/commands/deploy-to-stage.md @@ -0,0 +1,99 @@ +--- +description: "PASO 7 — Publica a main con squash merge. Requiere que el PR esté aprobado." +--- + +## Propósito + +Fusiona la feature a `main` con squash merge — todos los commits de iteración se aplanan en uno solo. GitHub Actions despliega automáticamente al detectar el merge. + +--- + +## Ejecución + +### 1. Verificar rama y PR + +```bash +git branch --show-current +gh pr view --json number,state,url,body,reviewDecision +``` + +- Si la rama es `main`: ERROR "Ya estás en main." +- Si no hay PR: ERROR "No hay PR abierto para esta rama." + +### 2. Gate: código entregado + +Verificar en el body del PR: `- [x] En revisión de código` + +Si no está marcado: ERROR "El código no ha sido entregado. Ejecuta /submit primero." + +### 3. Gate: PR aprobado + +Comprobar `reviewDecision`. + +Si NO es `APPROVED`: + +``` +🚫 BLOQUEADO + +El PR no tiene aprobación todavía. + +El equipo debe revisar y aprobar el PR en GitHub +antes de poder publicar a main. + +🔗 PR: +``` + +**PARAR.** + +### 4. Squash merge a main + +```bash +gh pr merge --squash --delete-branch +``` + +Si falla por conflictos: + +``` +🚫 ERROR: Hay conflictos al fusionar con main. + +No se ha realizado ningún cambio. +Resuelve los conflictos manualmente antes de continuar. +``` + +**PARAR.** + +### 5. Verificar que GitHub Actions se ha disparado + +```bash +gh run list --limit 3 +``` + +Mostrar los workflows activos para confirmar que el deploy arrancó. + +### 6. Informe final + +``` +✅ Publicado en main + +🌿 Fusionado: → main (squash) +🗑️ Rama eliminada +🚀 Deploy en curso — GitHub Actions desplegando + +───────────────────────────────────────── +Esta feature está completa. +───────────────────────────────────────── +``` + +### Cierre de sesión + +Leer el contexto actual de la sesión (igual que `/context`). + +- **🟢 / 🟡**: No mostrar nada. +- **🟠**: Mostrar al final del informe: + ``` + 🟠 El contexto está alto. Abre una sesión nueva antes del siguiente comando. + ``` +- **🔴**: Mostrar antes del informe final e interrumpir si el usuario intenta continuar: + ``` + 🔴 Contexto crítico. Abre una sesión nueva AHORA antes de continuar. + ``` diff --git a/.claude/commands/implement.md b/.claude/commands/implement.md new file mode 100644 index 0000000000..ab70146460 --- /dev/null +++ b/.claude/commands/implement.md @@ -0,0 +1,106 @@ +--- +description: "PASO 5 — Genera el código. Ejecutar cuando las tareas estén generadas y el equipo esté listo para implementar." +--- + +## Ejecución + +### 1. Verificar rama y PR + +```bash +git branch --show-current +gh pr view --json number,state,url,body +``` + +- Si la rama es `main` o `master`: ERROR "No estás en una rama de feature. Ejecuta /status." +- Si no hay PR: ERROR "No hay PR abierto. ¿Ejecutaste /start?" + +### 2. Gate: tareas generadas + +Verificar en el body del PR: +- `- [x] Spec creado` ✓ +- `- [x] Spec aprobado por el equipo de desarrollo` ✓ +- `- [x] Plan generado` ✓ +- `- [x] Plan aprobado por el equipo de desarrollo` ✓ +- `- [x] Tareas generadas` ✓ + +Si las tareas no están generadas: + +``` +🚫 BLOQUEADO + +Las tareas no han sido generadas todavía. +Ejecuta /tasks primero. +``` + +**PARAR.** + +### 3. Verificar estado limpio del repo + +```bash +git status --porcelain +``` + +Si hay cambios sin commitear: ERROR "Hay cambios sin guardar. Haz commit antes de implementar." + +### 4. Sync con main + +```bash +git fetch origin +git rebase origin/main +``` + +Si hay conflictos: ERROR "Hay conflictos con main. El equipo de desarrollo debe resolverlos antes de continuar." + +### 5. Delegar en speckit.implement + +Invocar `/speckit.implement`. + +`speckit.implement` se encarga de: +- Leer spec, plan, data-model, contracts y tasks +- Implementar las tareas en el orden correcto +- Respetar las dependencias definidas en tasks.md + +**Esperar a que `speckit.implement` termine completamente antes de continuar.** +Si produce ERROR: propagar y parar. + +### 6. Actualizar estado del PR + +Marcar: `- [x] Código generado` + +Añadir fila: +``` +| Código generado | YYYY-MM-DD | speckit.implement completado | +``` + +```bash +gh pr edit --body "" +``` + +### 7. Informe final + +``` +✅ Código generado + +───────────────────────────────────────── +➡️ SIGUIENTE PASO +───────────────────────────────────────── +Ejecuta: /submit + +Guardará el código y lo dejará listo +para revisión del equipo de desarrollo. +───────────────────────────────────────── +``` + +### Cierre de sesión + +Leer el contexto actual de la sesión (igual que `/context`). + +- **🟢 / 🟡**: No mostrar nada. +- **🟠**: Mostrar al final del informe: + ``` + 🟠 El contexto está alto. Abre una sesión nueva antes del siguiente comando. + ``` +- **🔴**: Mostrar antes del informe final e interrumpir si el usuario intenta continuar: + ``` + 🔴 Contexto crítico. Abre una sesión nueva AHORA antes de continuar. + ``` diff --git a/.claude/commands/plan.md b/.claude/commands/plan.md new file mode 100644 index 0000000000..56c7c7afe3 --- /dev/null +++ b/.claude/commands/plan.md @@ -0,0 +1,116 @@ +--- +description: "PASO 3 — Genera el plan técnico. Ejecutar cuando el equipo haya aprobado el spec." +--- + +## Ejecución + +### 1. Verificar rama y PR + +```bash +git branch --show-current +gh pr view --json number,state,url,body +``` + +- Si la rama es `main` o `master`: ERROR "No estás en una rama de feature. Ejecuta /status." +- Si no hay PR: ERROR "No hay PR abierto. ¿Ejecutaste /start?" + +### 2. Gate: spec aprobado + +Verificar en el body del PR: +- `- [x] Spec creado` ✓ +- `- [x] Spec aprobado por el equipo de desarrollo` ✓ + +Si la aprobación no está marcada: + +``` +🚫 BLOQUEADO + +El spec no ha sido aprobado todavía. + +El equipo de desarrollo debe aprobar el spec +en el PR antes de generar el plan. + +Si ya comentaron pero no aprobaron: + Ejecuta /consolidate-spec primero. +``` + +**PARAR.** + +### 3. Delegar en speckit.plan + +Invocar `/speckit.plan`. + +`speckit.plan` se encarga de: +- Ejecutar los scripts de setup del plan +- Generar `research.md` resolviendo incógnitas técnicas +- Generar `data-model.md` con entidades y relaciones +- Generar `contracts/` con los contratos de interfaz +- Actualizar el contexto del agente + +**Esperar a que `speckit.plan` termine completamente antes de continuar.** +Si produce ERROR: propagar y parar. + +### 4. Verificar artefactos generados + +```bash +ls specs// +``` + +Confirmar que existen: `research.md`, `data-model.md`. +Si faltan: ERROR "speckit.plan no generó todos los artefactos. Revisa los errores anteriores." + +### 5. Commit del plan + +```bash +git add specs/ +git commit -m "docs: añadir plan técnico" +git push origin HEAD +``` + +### 6. Actualizar estado del PR + +Marcar: `- [x] Plan generado` + +Añadir fila: +``` +| Plan generado | YYYY-MM-DD | research.md + data-model.md | +``` + +```bash +gh pr edit --body "" +``` + +### 7. Informe final + +``` +✅ Plan técnico generado + +📁 Artefactos: + specs//research.md + specs//data-model.md + specs//contracts/ (si aplica) + +───────────────────────────────────────── +➡️ SIGUIENTE PASO +───────────────────────────────────────── +Comparte el PR con el equipo para que +revisen el plan técnico. + +Cuando el equipo apruebe el plan, ejecuta: +/tasks +───────────────────────────────────────── +``` + +### Cierre de sesión + +Leer el contexto actual de la sesión (igual que `/context`). + +- **🟢 / 🟡**: No mostrar nada. +- **🟠**: Mostrar al final del informe: + ``` + 🟠 El contexto está alto. Abre una sesión nueva antes del siguiente comando. + ``` +- **🔴**: Mostrar antes del informe final e interrumpir si el usuario intenta continuar: + ``` + 🔴 Contexto crítico. Abre una sesión nueva AHORA antes de continuar. + ``` diff --git a/.claude/commands/speckit.analyze.md b/.claude/commands/speckit.analyze.md new file mode 100644 index 0000000000..98b04b0c88 --- /dev/null +++ b/.claude/commands/speckit.analyze.md @@ -0,0 +1,184 @@ +--- +description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation. +--- + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Goal + +Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/speckit.tasks` has successfully produced a complete `tasks.md`. + +## Operating Constraints + +**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually). + +**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/speckit.analyze`. + +## Execution Steps + +### 1. Initialize Analysis Context + +Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths: + +- SPEC = FEATURE_DIR/spec.md +- PLAN = FEATURE_DIR/plan.md +- TASKS = FEATURE_DIR/tasks.md + +Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command). +For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). + +### 2. Load Artifacts (Progressive Disclosure) + +Load only the minimal necessary context from each artifact: + +**From spec.md:** + +- Overview/Context +- Functional Requirements +- Non-Functional Requirements +- User Stories +- Edge Cases (if present) + +**From plan.md:** + +- Architecture/stack choices +- Data Model references +- Phases +- Technical constraints + +**From tasks.md:** + +- Task IDs +- Descriptions +- Phase grouping +- Parallel markers [P] +- Referenced file paths + +**From constitution:** + +- Load `.specify/memory/constitution.md` for principle validation + +### 3. Build Semantic Models + +Create internal representations (do not include raw artifacts in output): + +- **Requirements inventory**: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" → `user-can-upload-file`) +- **User story/action inventory**: Discrete user actions with acceptance criteria +- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases) +- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements + +### 4. Detection Passes (Token-Efficient Analysis) + +Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary. + +#### A. Duplication Detection + +- Identify near-duplicate requirements +- Mark lower-quality phrasing for consolidation + +#### B. Ambiguity Detection + +- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria +- Flag unresolved placeholders (TODO, TKTK, ???, ``, etc.) + +#### C. Underspecification + +- Requirements with verbs but missing object or measurable outcome +- User stories missing acceptance criteria alignment +- Tasks referencing files or components not defined in spec/plan + +#### D. Constitution Alignment + +- Any requirement or plan element conflicting with a MUST principle +- Missing mandated sections or quality gates from constitution + +#### E. Coverage Gaps + +- Requirements with zero associated tasks +- Tasks with no mapped requirement/story +- Non-functional requirements not reflected in tasks (e.g., performance, security) + +#### F. Inconsistency + +- Terminology drift (same concept named differently across files) +- Data entities referenced in plan but absent in spec (or vice versa) +- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note) +- Conflicting requirements (e.g., one requires Next.js while other specifies Vue) + +### 5. Severity Assignment + +Use this heuristic to prioritize findings: + +- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality +- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion +- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case +- **LOW**: Style/wording improvements, minor redundancy not affecting execution order + +### 6. Produce Compact Analysis Report + +Output a Markdown report (no file writes) with the following structure: + +## Specification Analysis Report + +| ID | Category | Severity | Location(s) | Summary | Recommendation | +|----|----------|----------|-------------|---------|----------------| +| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version | + +(Add one row per finding; generate stable IDs prefixed by category initial.) + +**Coverage Summary Table:** + +| Requirement Key | Has Task? | Task IDs | Notes | +|-----------------|-----------|----------|-------| + +**Constitution Alignment Issues:** (if any) + +**Unmapped Tasks:** (if any) + +**Metrics:** + +- Total Requirements +- Total Tasks +- Coverage % (requirements with >=1 task) +- Ambiguity Count +- Duplication Count +- Critical Issues Count + +### 7. Provide Next Actions + +At end of report, output a concise Next Actions block: + +- If CRITICAL issues exist: Recommend resolving before `/speckit.implement` +- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions +- Provide explicit command suggestions: e.g., "Run /speckit.specify with refinement", "Run /speckit.plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'" + +### 8. Offer Remediation + +Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.) + +## Operating Principles + +### Context Efficiency + +- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation +- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis +- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow +- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts + +### Analysis Guidelines + +- **NEVER modify files** (this is read-only analysis) +- **NEVER hallucinate missing sections** (if absent, report them accurately) +- **Prioritize constitution violations** (these are always CRITICAL) +- **Use examples over exhaustive rules** (cite specific instances, not generic patterns) +- **Report zero issues gracefully** (emit success report with coverage statistics) + +## Context + +$ARGUMENTS diff --git a/.claude/commands/speckit.checklist.md b/.claude/commands/speckit.checklist.md new file mode 100644 index 0000000000..b7624e226e --- /dev/null +++ b/.claude/commands/speckit.checklist.md @@ -0,0 +1,295 @@ +--- +description: Generate a custom checklist for the current feature based on user requirements. +--- + +## Checklist Purpose: "Unit Tests for English" + +**CRITICAL CONCEPT**: Checklists are **UNIT TESTS FOR REQUIREMENTS WRITING** - they validate the quality, clarity, and completeness of requirements in a given domain. + +**NOT for verification/testing**: + +- ❌ NOT "Verify the button clicks correctly" +- ❌ NOT "Test error handling works" +- ❌ NOT "Confirm the API returns 200" +- ❌ NOT checking if code/implementation matches the spec + +**FOR requirements quality validation**: + +- ✅ "Are visual hierarchy requirements defined for all card types?" (completeness) +- ✅ "Is 'prominent display' quantified with specific sizing/positioning?" (clarity) +- ✅ "Are hover state requirements consistent across all interactive elements?" (consistency) +- ✅ "Are accessibility requirements defined for keyboard navigation?" (coverage) +- ✅ "Does the spec define what happens when logo image fails to load?" (edge cases) + +**Metaphor**: If your spec is code written in English, the checklist is its unit test suite. You're testing whether the requirements are well-written, complete, unambiguous, and ready for implementation - NOT whether the implementation works. + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Execution Steps + +1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS list. + - All file paths must be absolute. + - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). + +2. **Clarify intent (dynamic)**: Derive up to THREE initial contextual clarifying questions (no pre-baked catalog). They MUST: + - Be generated from the user's phrasing + extracted signals from spec/plan/tasks + - Only ask about information that materially changes checklist content + - Be skipped individually if already unambiguous in `$ARGUMENTS` + - Prefer precision over breadth + + Generation algorithm: + 1. Extract signals: feature domain keywords (e.g., auth, latency, UX, API), risk indicators ("critical", "must", "compliance"), stakeholder hints ("QA", "review", "security team"), and explicit deliverables ("a11y", "rollback", "contracts"). + 2. Cluster signals into candidate focus areas (max 4) ranked by relevance. + 3. Identify probable audience & timing (author, reviewer, QA, release) if not explicit. + 4. Detect missing dimensions: scope breadth, depth/rigor, risk emphasis, exclusion boundaries, measurable acceptance criteria. + 5. Formulate questions chosen from these archetypes: + - Scope refinement (e.g., "Should this include integration touchpoints with X and Y or stay limited to local module correctness?") + - Risk prioritization (e.g., "Which of these potential risk areas should receive mandatory gating checks?") + - Depth calibration (e.g., "Is this a lightweight pre-commit sanity list or a formal release gate?") + - Audience framing (e.g., "Will this be used by the author only or peers during PR review?") + - Boundary exclusion (e.g., "Should we explicitly exclude performance tuning items this round?") + - Scenario class gap (e.g., "No recovery flows detected—are rollback / partial failure paths in scope?") + + Question formatting rules: + - If presenting options, generate a compact table with columns: Option | Candidate | Why It Matters + - Limit to A–E options maximum; omit table if a free-form answer is clearer + - Never ask the user to restate what they already said + - Avoid speculative categories (no hallucination). If uncertain, ask explicitly: "Confirm whether X belongs in scope." + + Defaults when interaction impossible: + - Depth: Standard + - Audience: Reviewer (PR) if code-related; Author otherwise + - Focus: Top 2 relevance clusters + + Output the questions (label Q1/Q2/Q3). After answers: if ≥2 scenario classes (Alternate / Exception / Recovery / Non-Functional domain) remain unclear, you MAY ask up to TWO more targeted follow‑ups (Q4/Q5) with a one-line justification each (e.g., "Unresolved recovery path risk"). Do not exceed five total questions. Skip escalation if user explicitly declines more. + +3. **Understand user request**: Combine `$ARGUMENTS` + clarifying answers: + - Derive checklist theme (e.g., security, review, deploy, ux) + - Consolidate explicit must-have items mentioned by user + - Map focus selections to category scaffolding + - Infer any missing context from spec/plan/tasks (do NOT hallucinate) + +4. **Load feature context**: Read from FEATURE_DIR: + - spec.md: Feature requirements and scope + - plan.md (if exists): Technical details, dependencies + - tasks.md (if exists): Implementation tasks + + **Context Loading Strategy**: + - Load only necessary portions relevant to active focus areas (avoid full-file dumping) + - Prefer summarizing long sections into concise scenario/requirement bullets + - Use progressive disclosure: add follow-on retrieval only if gaps detected + - If source docs are large, generate interim summary items instead of embedding raw text + +5. **Generate checklist** - Create "Unit Tests for Requirements": + - Create `FEATURE_DIR/checklists/` directory if it doesn't exist + - Generate unique checklist filename: + - Use short, descriptive name based on domain (e.g., `ux.md`, `api.md`, `security.md`) + - Format: `[domain].md` + - File handling behavior: + - If file does NOT exist: Create new file and number items starting from CHK001 + - If file exists: Append new items to existing file, continuing from the last CHK ID (e.g., if last item is CHK015, start new items at CHK016) + - Never delete or replace existing checklist content - always preserve and append + + **CORE PRINCIPLE - Test the Requirements, Not the Implementation**: + Every checklist item MUST evaluate the REQUIREMENTS THEMSELVES for: + - **Completeness**: Are all necessary requirements present? + - **Clarity**: Are requirements unambiguous and specific? + - **Consistency**: Do requirements align with each other? + - **Measurability**: Can requirements be objectively verified? + - **Coverage**: Are all scenarios/edge cases addressed? + + **Category Structure** - Group items by requirement quality dimensions: + - **Requirement Completeness** (Are all necessary requirements documented?) + - **Requirement Clarity** (Are requirements specific and unambiguous?) + - **Requirement Consistency** (Do requirements align without conflicts?) + - **Acceptance Criteria Quality** (Are success criteria measurable?) + - **Scenario Coverage** (Are all flows/cases addressed?) + - **Edge Case Coverage** (Are boundary conditions defined?) + - **Non-Functional Requirements** (Performance, Security, Accessibility, etc. - are they specified?) + - **Dependencies & Assumptions** (Are they documented and validated?) + - **Ambiguities & Conflicts** (What needs clarification?) + + **HOW TO WRITE CHECKLIST ITEMS - "Unit Tests for English"**: + + ❌ **WRONG** (Testing implementation): + - "Verify landing page displays 3 episode cards" + - "Test hover states work on desktop" + - "Confirm logo click navigates home" + + ✅ **CORRECT** (Testing requirements quality): + - "Are the exact number and layout of featured episodes specified?" [Completeness] + - "Is 'prominent display' quantified with specific sizing/positioning?" [Clarity] + - "Are hover state requirements consistent across all interactive elements?" [Consistency] + - "Are keyboard navigation requirements defined for all interactive UI?" [Coverage] + - "Is the fallback behavior specified when logo image fails to load?" [Edge Cases] + - "Are loading states defined for asynchronous episode data?" [Completeness] + - "Does the spec define visual hierarchy for competing UI elements?" [Clarity] + + **ITEM STRUCTURE**: + Each item should follow this pattern: + - Question format asking about requirement quality + - Focus on what's WRITTEN (or not written) in the spec/plan + - Include quality dimension in brackets [Completeness/Clarity/Consistency/etc.] + - Reference spec section `[Spec §X.Y]` when checking existing requirements + - Use `[Gap]` marker when checking for missing requirements + + **EXAMPLES BY QUALITY DIMENSION**: + + Completeness: + - "Are error handling requirements defined for all API failure modes? [Gap]" + - "Are accessibility requirements specified for all interactive elements? [Completeness]" + - "Are mobile breakpoint requirements defined for responsive layouts? [Gap]" + + Clarity: + - "Is 'fast loading' quantified with specific timing thresholds? [Clarity, Spec §NFR-2]" + - "Are 'related episodes' selection criteria explicitly defined? [Clarity, Spec §FR-5]" + - "Is 'prominent' defined with measurable visual properties? [Ambiguity, Spec §FR-4]" + + Consistency: + - "Do navigation requirements align across all pages? [Consistency, Spec §FR-10]" + - "Are card component requirements consistent between landing and detail pages? [Consistency]" + + Coverage: + - "Are requirements defined for zero-state scenarios (no episodes)? [Coverage, Edge Case]" + - "Are concurrent user interaction scenarios addressed? [Coverage, Gap]" + - "Are requirements specified for partial data loading failures? [Coverage, Exception Flow]" + + Measurability: + - "Are visual hierarchy requirements measurable/testable? [Acceptance Criteria, Spec §FR-1]" + - "Can 'balanced visual weight' be objectively verified? [Measurability, Spec §FR-2]" + + **Scenario Classification & Coverage** (Requirements Quality Focus): + - Check if requirements exist for: Primary, Alternate, Exception/Error, Recovery, Non-Functional scenarios + - For each scenario class, ask: "Are [scenario type] requirements complete, clear, and consistent?" + - If scenario class missing: "Are [scenario type] requirements intentionally excluded or missing? [Gap]" + - Include resilience/rollback when state mutation occurs: "Are rollback requirements defined for migration failures? [Gap]" + + **Traceability Requirements**: + - MINIMUM: ≥80% of items MUST include at least one traceability reference + - Each item should reference: spec section `[Spec §X.Y]`, or use markers: `[Gap]`, `[Ambiguity]`, `[Conflict]`, `[Assumption]` + - If no ID system exists: "Is a requirement & acceptance criteria ID scheme established? [Traceability]" + + **Surface & Resolve Issues** (Requirements Quality Problems): + Ask questions about the requirements themselves: + - Ambiguities: "Is the term 'fast' quantified with specific metrics? [Ambiguity, Spec §NFR-1]" + - Conflicts: "Do navigation requirements conflict between §FR-10 and §FR-10a? [Conflict]" + - Assumptions: "Is the assumption of 'always available podcast API' validated? [Assumption]" + - Dependencies: "Are external podcast API requirements documented? [Dependency, Gap]" + - Missing definitions: "Is 'visual hierarchy' defined with measurable criteria? [Gap]" + + **Content Consolidation**: + - Soft cap: If raw candidate items > 40, prioritize by risk/impact + - Merge near-duplicates checking the same requirement aspect + - If >5 low-impact edge cases, create one item: "Are edge cases X, Y, Z addressed in requirements? [Coverage]" + + **🚫 ABSOLUTELY PROHIBITED** - These make it an implementation test, not a requirements test: + - ❌ Any item starting with "Verify", "Test", "Confirm", "Check" + implementation behavior + - ❌ References to code execution, user actions, system behavior + - ❌ "Displays correctly", "works properly", "functions as expected" + - ❌ "Click", "navigate", "render", "load", "execute" + - ❌ Test cases, test plans, QA procedures + - ❌ Implementation details (frameworks, APIs, algorithms) + + **✅ REQUIRED PATTERNS** - These test requirements quality: + - ✅ "Are [requirement type] defined/specified/documented for [scenario]?" + - ✅ "Is [vague term] quantified/clarified with specific criteria?" + - ✅ "Are requirements consistent between [section A] and [section B]?" + - ✅ "Can [requirement] be objectively measured/verified?" + - ✅ "Are [edge cases/scenarios] addressed in requirements?" + - ✅ "Does the spec define [missing aspect]?" + +6. **Structure Reference**: Generate the checklist following the canonical template in `.specify/templates/checklist-template.md` for title, meta section, category headings, and ID formatting. If template is unavailable, use: H1 title, purpose/created meta lines, `##` category sections containing `- [ ] CHK### ` lines with globally incrementing IDs starting at CHK001. + +7. **Report**: Output full path to checklist file, item count, and summarize whether the run created a new file or appended to an existing one. Summarize: + - Focus areas selected + - Depth level + - Actor/timing + - Any explicit user-specified must-have items incorporated + +**Important**: Each `/speckit.checklist` command invocation uses a short, descriptive checklist filename and either creates a new file or appends to an existing one. This allows: + +- Multiple checklists of different types (e.g., `ux.md`, `test.md`, `security.md`) +- Simple, memorable filenames that indicate checklist purpose +- Easy identification and navigation in the `checklists/` folder + +To avoid clutter, use descriptive types and clean up obsolete checklists when done. + +## Example Checklist Types & Sample Items + +**UX Requirements Quality:** `ux.md` + +Sample items (testing the requirements, NOT the implementation): + +- "Are visual hierarchy requirements defined with measurable criteria? [Clarity, Spec §FR-1]" +- "Is the number and positioning of UI elements explicitly specified? [Completeness, Spec §FR-1]" +- "Are interaction state requirements (hover, focus, active) consistently defined? [Consistency]" +- "Are accessibility requirements specified for all interactive elements? [Coverage, Gap]" +- "Is fallback behavior defined when images fail to load? [Edge Case, Gap]" +- "Can 'prominent display' be objectively measured? [Measurability, Spec §FR-4]" + +**API Requirements Quality:** `api.md` + +Sample items: + +- "Are error response formats specified for all failure scenarios? [Completeness]" +- "Are rate limiting requirements quantified with specific thresholds? [Clarity]" +- "Are authentication requirements consistent across all endpoints? [Consistency]" +- "Are retry/timeout requirements defined for external dependencies? [Coverage, Gap]" +- "Is versioning strategy documented in requirements? [Gap]" + +**Performance Requirements Quality:** `performance.md` + +Sample items: + +- "Are performance requirements quantified with specific metrics? [Clarity]" +- "Are performance targets defined for all critical user journeys? [Coverage]" +- "Are performance requirements under different load conditions specified? [Completeness]" +- "Can performance requirements be objectively measured? [Measurability]" +- "Are degradation requirements defined for high-load scenarios? [Edge Case, Gap]" + +**Security Requirements Quality:** `security.md` + +Sample items: + +- "Are authentication requirements specified for all protected resources? [Coverage]" +- "Are data protection requirements defined for sensitive information? [Completeness]" +- "Is the threat model documented and requirements aligned to it? [Traceability]" +- "Are security requirements consistent with compliance obligations? [Consistency]" +- "Are security failure/breach response requirements defined? [Gap, Exception Flow]" + +## Anti-Examples: What NOT To Do + +**❌ WRONG - These test implementation, not requirements:** + +```markdown +- [ ] CHK001 - Verify landing page displays 3 episode cards [Spec §FR-001] +- [ ] CHK002 - Test hover states work correctly on desktop [Spec §FR-003] +- [ ] CHK003 - Confirm logo click navigates to home page [Spec §FR-010] +- [ ] CHK004 - Check that related episodes section shows 3-5 items [Spec §FR-005] +``` + +**✅ CORRECT - These test requirements quality:** + +```markdown +- [ ] CHK001 - Are the number and layout of featured episodes explicitly specified? [Completeness, Spec §FR-001] +- [ ] CHK002 - Are hover state requirements consistently defined for all interactive elements? [Consistency, Spec §FR-003] +- [ ] CHK003 - Are navigation requirements clear for all clickable brand elements? [Clarity, Spec §FR-010] +- [ ] CHK004 - Is the selection criteria for related episodes documented? [Gap, Spec §FR-005] +- [ ] CHK005 - Are loading state requirements defined for asynchronous episode data? [Gap] +- [ ] CHK006 - Can "visual hierarchy" requirements be objectively measured? [Measurability, Spec §FR-001] +``` + +**Key Differences:** + +- Wrong: Tests if the system works correctly +- Correct: Tests if the requirements are written correctly +- Wrong: Verification of behavior +- Correct: Validation of requirement quality +- Wrong: "Does it do X?" +- Correct: "Is X clearly specified?" diff --git a/.claude/commands/speckit.clarify.md b/.claude/commands/speckit.clarify.md new file mode 100644 index 0000000000..f2a9696e86 --- /dev/null +++ b/.claude/commands/speckit.clarify.md @@ -0,0 +1,181 @@ +--- +description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec. +handoffs: + - label: Build Technical Plan + agent: speckit.plan + prompt: Create a plan for the spec. I am building with... +--- + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Outline + +Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file. + +Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/speckit.plan`. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases. + +Execution steps: + +1. Run `.specify/scripts/bash/check-prerequisites.sh --json --paths-only` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields: + - `FEATURE_DIR` + - `FEATURE_SPEC` + - (Optionally capture `IMPL_PLAN`, `TASKS` for future chained flows.) + - If JSON parsing fails, abort and instruct user to re-run `/speckit.specify` or verify feature branch environment. + - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). + +2. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked). + + Functional Scope & Behavior: + - Core user goals & success criteria + - Explicit out-of-scope declarations + - User roles / personas differentiation + + Domain & Data Model: + - Entities, attributes, relationships + - Identity & uniqueness rules + - Lifecycle/state transitions + - Data volume / scale assumptions + + Interaction & UX Flow: + - Critical user journeys / sequences + - Error/empty/loading states + - Accessibility or localization notes + + Non-Functional Quality Attributes: + - Performance (latency, throughput targets) + - Scalability (horizontal/vertical, limits) + - Reliability & availability (uptime, recovery expectations) + - Observability (logging, metrics, tracing signals) + - Security & privacy (authN/Z, data protection, threat assumptions) + - Compliance / regulatory constraints (if any) + + Integration & External Dependencies: + - External services/APIs and failure modes + - Data import/export formats + - Protocol/versioning assumptions + + Edge Cases & Failure Handling: + - Negative scenarios + - Rate limiting / throttling + - Conflict resolution (e.g., concurrent edits) + + Constraints & Tradeoffs: + - Technical constraints (language, storage, hosting) + - Explicit tradeoffs or rejected alternatives + + Terminology & Consistency: + - Canonical glossary terms + - Avoided synonyms / deprecated terms + + Completion Signals: + - Acceptance criteria testability + - Measurable Definition of Done style indicators + + Misc / Placeholders: + - TODO markers / unresolved decisions + - Ambiguous adjectives ("robust", "intuitive") lacking quantification + + For each category with Partial or Missing status, add a candidate question opportunity unless: + - Clarification would not materially change implementation or validation strategy + - Information is better deferred to planning phase (note internally) + +3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints: + - Maximum of 5 total questions across the whole session. + - Each question must be answerable with EITHER: + - A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR + - A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words"). + - Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation. + - Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved. + - Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness). + - Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests. + - If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic. + +4. Sequential questioning loop (interactive): + - Present EXACTLY ONE question at a time. + - For multiple‑choice questions: + - **Analyze all options** and determine the **most suitable option** based on: + - Best practices for the project type + - Common patterns in similar implementations + - Risk reduction (security, performance, maintainability) + - Alignment with any explicit project goals or constraints visible in the spec + - Present your **recommended option prominently** at the top with clear reasoning (1-2 sentences explaining why this is the best choice). + - Format as: `**Recommended:** Option [X] - ` + - Then render all options as a Markdown table: + + | Option | Description | + |--------|-------------| + | A |