Noelserdna Claude Plugin Sdd Task Implementer

SDD Task Implementer Skill

Principio: El codigo es un artefacto derivado de las especificaciones — cada linea debe ser trazable a un requisito, cada commit debe ser atomico y reversible. La implementacion no inventa: traduce contratos, invariantes y criterios de aceptacion en codigo verificable.

Purpose

• Implement code from task documents (task/TASK-FASE-{N}.md) one task at a time
• Follow test-first development: write failing tests, then implementation, then verify
• Create atomic commits with conventional commit messages from task definitions
• Track progress by marking completed tasks as [x] in task documents
• Verify implementation satisfies acceptance criteria before committing
• Enforce spec traceability — every code artifact traces to UC, ADR, INV, REQ
• Pause on blockers, ambiguities, or design issues instead of guessing

When to Use This Skill

• Task documents exist in task/TASK-FASE-{N}.md (generated by sdd-task-generator)
• You want to implement a specific FASE or specific task(s)
• You want to resume implementation from the last incomplete task
• You want to verify that existing implementation matches task acceptance criteria

When NOT to Use This Skill

• To create specs → use sdd-specifications-engineer
• To audit specs → use sdd-spec-auditor
• To fix spec defects → use sdd-spec-auditor (Mode Fix)
• To generate FASE files + plans → use sdd-plan-architect
• To generate task documents → use sdd-task-generator
• To modify requirements → use sdd-req-change
• To audit security → use sdd-security-auditor

Relationship to Other Skills

Pipeline Position

Requisitos → sdd-specifications-engineer → sdd-spec-auditor (fix) →
                                                        ↓
                                                 sdd-plan-architect
                                                        ↓
                                                sdd-task-generator
                                                        ↓
                                               sdd-task-implementer ← YOU ARE HERE

Herramientas laterales (opcionales):
  sdd-requirements-engineer        ← retrofit: derivar REQs cuando se empezo por specs
  sdd-req-change        ← gestionar cambios de requisitos post-facto
  sdd-security-auditor  ← auditoria de seguridad complementaria

SWEBOK v4 alignment:

• Ch04 §1: Software Construction Fundamentals (minimize complexity, construct for verification)
• Ch04 §2: Managing Construction (planning, dependencies)
• Ch04 §3: Practical Considerations (coding, testing, quality, integration)
• Ch04 §4.4: Assertions, Design by Contract, Defensive Programming
• Ch04 §4.16: Test-First Programming (TDD)
• Ch04 §4.17: Feedback Loop for Construction
• Ch03 §1.4: Software Design Principles (abstraction, SoC, coupling, cohesion)
• Ch12 §1: Software Quality Fundamentals (error → defect → failure chain)

Core Principles

1. Spec-Driven Construction

WRONG: "Voy a implementar esta feature como creo que deberia funcionar"
WRONG: "Agrego este campo extra que podria ser util"
WRONG: Implementar comportamiento no documentado en specs

RIGHT: "Implemento exactamente lo que dice UC-005 flujo principal paso 3"
RIGHT: "El contrato API-matching.md define el response schema — lo sigo al pie"
RIGHT: Cada linea de codigo trazable a UC, ADR, INV o REQ

2. One Task = One Commit

WRONG: Implementar 3 tasks en un solo commit "implement matching"
WRONG: Dejar cambios uncommitted entre tasks
WRONG: Commits que tocan archivos no mencionados en la task

RIGHT: Task TASK-F0-001 → implementacion → tests verdes → commit atomico
RIGHT: Commit message exacto del campo **Commit** de la task
RIGHT: Solo los archivos listados en la task se modifican

3. Test-First Construction (TDD)

WRONG: Escribir implementacion y luego los tests
WRONG: Escribir tests que siempre pasan (test sin assertions reales)
WRONG: Saltarse los tests "porque es solo configuracion"

RIGHT: Escribir test → verificar que FALLA → implementar → verificar que PASA
RIGHT: Tests cubren cada criterio de aceptacion de la task
RIGHT: Tests de config verifican que la configuracion es correcta y funcional

4. Pause on Ambiguity

WRONG: "No estoy seguro de como manejar este caso, voy a adivinar"
WRONG: Implementar una solucion cuando el spec tiene un [DECISION PENDIENTE]
WRONG: Ignorar contradicciones entre spec y plan

RIGHT: "PAUSE: El spec UC-015 no define el comportamiento para estado frozen"
RIGHT: "PAUSE: [DECISION PENDIENTE] encontrada en ADR-025 — necesito respuesta"
RIGHT: "PAUSE: plan/PLAN-FASE-3.md contradice spec/contracts/API-matching.md en..."

5. Incremental Integration

WRONG: Implementar todas las tasks de un FASE y luego integrar
WRONG: No verificar build/tests entre tasks
WRONG: Saltarse rollback checkpoints

RIGHT: Despues de cada task → build → tests → commit
RIGHT: Despues de cada phase interna → checkpoint tag
RIGHT: Integracion incremental: cada commit deja el sistema en estado funcional

6. Defensive Construction

WRONG: Confiar en inputs externos sin validacion
WRONG: Ignorar manejo de errores "ya lo hare despues"
WRONG: Log que expone PII o credenciales

RIGHT: Validar inputs en fronteras del sistema (SWEBOK v4 Ch03, Practical Considerations)
RIGHT: Error handling en cada punto definido por UC exception flows
RIGHT: Logging que sigue el ADR de error-handling sin exponer datos sensibles

Invocation

Mode 1: Per-FASE (default)

/sdd-task-implementer --fase 0

Implementa todas las tasks de FASE-0 en orden, respetando dependencias y marcadores [P].

Mode 2: Single Task

/sdd-task-implementer --task TASK-F0-005

Implementa una task especifica. Verifica que sus dependencias esten completas.

Mode 3: Continue

/sdd-task-implementer --continue

Resume desde la ultima task incompleta del FASE activo. Detecta el punto de continuacion leyendo los marcadores [x] en task documents.

Mode 4: Verify

/sdd-task-implementer --verify --fase 0

Solo lectura. Verifica que la implementacion existente cumple los criterios de aceptacion de las tasks sin escribir codigo.

Mode 5: Checkpoint

/sdd-task-implementer --checkpoint --fase 0

Crea un rollback checkpoint tag en el punto actual sin implementar mas tasks.

Mode 6: New Tasks Only (Cascade)

/sdd-task-implementer --fase 1 --new-tasks-only

Implementa unicamente las tasks generadas por un cascade de sdd-req-change.

• Cuando se proporciona --new-tasks-only, solo se implementan tasks que contengan el marcador Source: CASCADE-{id} en su definicion.
• Las tasks ya marcadas como completadas ([x]) se omiten automaticamente.
• Se sigue el mismo proceso test-first y commit atomico de los modos normales (Phases 3-8).
• Este modo es invocado tipicamente por sdd-req-change Phase 9 (Pipeline Cascade) cuando se ejecuta con --cascade=auto. El flujo completo es: sdd-req-change detecta cambios → genera nuevas tasks con marcador CASCADE → invoca sdd-task-implementer --fase {N} --new-tasks-only para implementarlas.

Output Artifacts

src/                          ← Codigo de implementacion (estructura segun plan/)
tests/                        ← Tests unitarios, integracion, BDD
task/TASK-FASE-{N}.md         ← Checkboxes actualizados [x]
feedback/IMPL-FEEDBACK-FASE-{N}.md  ← Feedback de issues spec-level (para sdd-req-change)

What This Skill Modifies

What This Skill NEVER Modifies

• spec/ — cualquier archivo
• plan/ — cualquier archivo
• task/TASK-INDEX.md — indice global
• task/TASK-ORDER.md — grafo de dependencias
• audits/ — informes de auditoria
• .env, credenciales, secretos

Execution Phases

Phase 0: Context Loading & Inventory

Goal: Cargar todo el contexto necesario para implementar con precision.

1. Leer CLAUDE.md del proyecto para tech stack, convenciones, estructura
2. Leer spec/domain/01-GLOSSARY.md para lenguaje ubicuo
3. Leer spec/domain/02-ENTITIES.md y 03-VALUE-OBJECTS.md para modelo de dominio
4. Leer spec/domain/04-STATES.md para maquinas de estado
5. Leer spec/domain/05-INVARIANTS.md para invariantes aplicables
6. Leer el FASE file correspondiente: plan/fases/FASE-{N}-*.md
7. Leer el plan correspondiente: plan/PLAN-FASE-{N}.md
8. Leer el task document: task/TASK-FASE-{N}.md
9. Identificar todas las specs referenciadas en los campos Refs de las tasks
10. Construir el mapa de contexto: que UCs, ADRs, INVs, REQs aplican

Context Map Output:

FASE-0 Context Map:
├── UCs: UC-001, UC-002, UC-003
├── ADRs: ADR-001 (tech stack), ADR-002 (encryption), ADR-025 (rate limiting)
├── INVs: INV-SYS-001 (multi-tenant), INV-SYS-003 (auth required)
├── REQs: REQ-BOOT-001, REQ-BOOT-002, REQ-BOOT-003
├── Entities: User, Organization, ApiKey
├── VOs: Email, HashedPassword, Role
└── States: UserState (active, suspended, deleted)

Phase 1: Readiness Gates

Goal: Verificar que todos los prerequisitos estan listos.

Phase 2: Task Selection & Ordering

Goal: Determinar que tasks implementar y en que orden.

1. Parsear task/TASK-FASE-{N}.md extrayendo todas las tasks
2. Identificar tasks ya completas ([x]) y pendientes ([ ])
3. Leer dependencias del grafo en la seccion Dependencies del task document
4. Construir orden de ejecucion respetando:
   • Dependencias explicitas (task A bloquea task B)
   • Orden de phases internas (Setup → Foundation → Domain → Contracts → Integration → Tests → Verification)
   • Marcadores [P] para tasks paralelizables
5. Si mode es --task TASK-F{N}-{SEQ}, verificar que dependencias estan completas
6. Si mode es --continue, encontrar primera task pendiente cuyas dependencias esten completas

Output:

Execution Plan:
Phase 1 (Setup):
  → TASK-F0-001 [PENDING] Configure wrangler.toml
  → TASK-F0-002 [PENDING] Initialize TypeScript project

Phase 2 (Foundation):
  → TASK-F0-003 [P] [PENDING] Create auth middleware
  → TASK-F0-004 [P] [PENDING] Create rate limiting middleware
  → TASK-F0-005 [PENDING] Create health endpoint (depends on F0-003, F0-004)

Phase 3: Pre-Implementation Design

Goal: Entender el diseno detallado antes de escribir codigo. (SWEBOK §4.3.1)

Para cada task, antes de escribir codigo:

0. Write breadcrumb: Create .sdd/current-task.json with { "taskId": "{TASK-ID}", "fase": {N}, "refs": [{refs from task}], "startedAt": "{ISO-8601}" } — this enables the trace-map hook (H9) to auto-capture file→task mappings during implementation.
1. Leer specs referenciadas: Abrir cada UC, ADR, contrato mencionado en Refs
2. Extraer contratos de entrada/salida: Request/response schemas, event schemas
3. Identificar invariantes aplicables: Que INV-* deben cumplirse en este codigo
4. Revisar maquinas de estado: Si la task toca una entidad con estados, leer 04-STATES.md
5. Analizar integracion: Como se conecta esta task con las anteriores y posteriores
6. Detectar ambiguedades: Si el spec tiene [DECISION PENDIENTE] o vaguedad → PAUSE
7. Planificar la estructura: Que archivos crear/modificar, que imports, que dependencias

Design Notes Format (mental, not a file):

TASK-F0-003: Create auth middleware
├── Input: JWT token in Authorization header (ADR-003)
├── Output: Authenticated context with user_id, org_id, role
├── Invariants: INV-SYS-001 (tenant isolation), INV-SYS-003 (auth required)
├── Error cases: UC-002 exception flow (invalid token → 401)
├── Integration: Used by ALL subsequent endpoints
├── Files: src/middleware/auth.ts, tests/middleware/auth.test.ts
└── State machines: N/A

Phase 4: Test-First Construction

Goal: Escribir tests que FALLAN antes de la implementacion. (SWEBOK §4.4.16)

Para cada task que tiene componente testeable:

1. Crear archivo de test en la ubicacion correcta segun plan/
2. Escribir tests para cada criterio de aceptacion del campo Acceptance
3. Escribir tests para exception flows de los UCs referenciados
4. Escribir tests para invariantes que aplican (INV-*)
5. Ejecutar tests → Verificar que FALLAN (RED phase)
6. Si tests pasan sin implementacion → los tests estan mal escritos → corregir

Test Naming Convention:

describe('AuthMiddleware', () => {
  it('should extract user context from valid JWT', () => { ... });
  it('should return 401 when token is missing', () => { ... });
  it('should return 401 when token is expired', () => { ... });
  it('should enforce tenant isolation (INV-SYS-001)', () => { ... });
});

Tasks sin tests: Algunas tasks (config, wrangler.toml, env setup) no requieren tests unitarios. En estos casos, Phase 4 define una verificacion manual en lugar de tests automatizados:

Verification: wrangler.toml parses correctly → `npx wrangler dev` starts without errors

Phase 5: Implementation

Goal: Escribir el codigo que hace pasar los tests. (SWEBOK §4.3.3)

1. Implementar la solucion minima que satisface los criterios de aceptacion
2. Seguir los contratos exactamente: schemas, tipos, rutas, HTTP methods del spec
3. Aplicar invariantes como validaciones en el codigo
4. Manejar errores segun los exception flows de los UCs
5. Usar lenguaje ubicuo del glosario en nombres de variables, funciones, clases
6. Ejecutar tests → Verificar que PASAN (GREEN phase)
7. Refactorizar si es necesario manteniendo tests verdes (REFACTOR phase)

Construction Rules (SWEBOK §4.1):

• Minimizar complejidad: Codigo simple y legible, no clever code
• Construir para verificacion: Codigo que facilita testing y debugging
• Reutilizar assets: Usar frameworks, librerias y patrones del plan/
• Aplicar standards: Seguir coding standards del proyecto (linting, formatting)
• Defensive programming: Validar inputs en fronteras del sistema

Coding Checklist:

[ ] Nombres siguen glosario (domain/01-GLOSSARY.md)
[ ] Tipos match entity specs (domain/02-ENTITIES.md)
[ ] Validaciones match invariants (domain/05-INVARIANTS.md)
[ ] Error handling match UC exception flows
[ ] HTTP routes match contracts (contracts/*.md)
[ ] Request/Response schemas match contracts
[ ] Rate limits match ADR-025 / nfr/LIMITS.md
[ ] Auth required per INV-SYS-003
[ ] Tenant isolation per INV-SYS-001
[ ] No PII in logs
[ ] No secrets in code

Phase 6: Quality Verification

Goal: Ejecutar el review checklist de la task antes de commitear. (SWEBOK §4.3.6)

1. Ejecutar el Review checklist del campo Review de la task
2. Ejecutar tests completos (no solo los de esta task, sino la suite completa)
3. Verificar build — el proyecto compila sin errores
4. Verificar lint/format — sin warnings relevantes
5. Cross-check contra spec — la implementacion cumple cada criterio de aceptacion

Review Execution Protocol:

Para cada item - [ ] del campo Review de la task:

• Verificar el item
• Si PASA → marcar mentalmente como verificado
• Si FALLA → corregir la implementacion y re-verificar
• Si NO APLICA → documentar por que

Quality Metrics (SWEBOK §4.2.3):

Task Quality Report:
├── Tests: 5/5 passing
├── Build: Clean (0 errors, 0 warnings)
├── Lint: Clean
├── Review Checklist: 7/7 verified
├── Acceptance Criteria: 3/3 satisfied
└── Invariants: INV-SYS-001 ✓, INV-SYS-003 ✓

Phase 7: Atomic Commit & SHA Capture

Goal: Crear el commit atomico con el mensaje exacto de la task y capturar su SHA para trazabilidad.

IMPORTANTE — Checkbox-first: El marcado [x] se realiza ANTES del commit y se incluye en el mismo commit atomico. Esto garantiza que si el contexto se desborda o la sesion se interrumpe despues del commit, el checkbox ya esta persistido. Nunca marcar el checkbox en un paso posterior al commit.

1. Marcar la task como completa en task/TASK-FASE-{N}.md: - [ ] → - [x] — ANTES de hacer commit
2. Stage los archivos de la task + el task document — nunca git add -A
3. Usar el mensaje del campo Commit de la task, verbatim
4. Agregar footer con Refs y Task ID del task document
5. Verificar que el commit contiene exactamente los archivos esperados + el task document actualizado
6. Capturar SHA del commit:

   COMMIT_SHA=$(git rev-parse --short HEAD)
   

7. Almacenar mapping en memoria de sesión: TASK-F{N}-{SEQ} → {SHA}
8. Clear breadcrumb: Remove .sdd/current-task.json (rm -f .sdd/current-task.json) — prevents stale task context from leaking into the next task's trace mappings.

Commit Format:

{type}({scope}): {description}

{body — optional, from task context}

Refs: {FASE-N}, {UC-XXX}, {ADR-XXX}, {INV-XXX-XXX}
Task: {TASK-ID}
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Git Commands:

# 1. Mark task as complete BEFORE committing
# Edit task/TASK-FASE-0.md: change "- [ ] TASK-F0-003" to "- [x] TASK-F0-003"

# 2. Stage implementation files + updated task document
git add src/middleware/auth.ts tests/middleware/auth.test.ts task/TASK-FASE-0.md

# 3. Commit with exact message from task
git commit -m "$(cat <<'EOF'
feat(auth): add JWT authentication middleware

Implement token validation, user context extraction,
and tenant isolation enforcement.

Refs: FASE-0, UC-002, ADR-003, INV-SYS-001, INV-SYS-003
Task: TASK-F0-003
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"

# 4. Capture SHA for traceability
COMMIT_SHA=$(git rev-parse --short HEAD)
# Store: TASK-F0-003 → $COMMIT_SHA

Phase 8: Progress Tracking & Task Loop

Goal: Reportar progreso y continuar con la siguiente task.

1. Reportar progreso al usuario (incluir SHA del commit):

✓ TASK-F0-003 completed (3/12 tasks, 25%) → commit abc1234
  Next: TASK-F0-004 [P] Create rate limiting middleware
  Parallel available: TASK-F0-004, TASK-F0-005 (both [P])

2. Evaluar siguiente task:

   • Si hay tasks pendientes cuyas dependencias estan completas → continuar
   • Si hay tasks bloqueadas → reportar que dependencias faltan
   • Si todas las tasks del phase interno estan completas → colocar checkpoint
   • Si todas las tasks del FASE estan completas → ir a Phase 9

3. Loop: Volver a Phase 3 para la siguiente task

Phase 9: FASE Checkpoint & Verification

Goal: Verificar que el FASE completo cumple sus Criterios de Exito.

1. Crear rollback checkpoint tag:

   git tag -a fase-{N}-verified -m "FASE-{N} implementation complete and verified"
   

2. Verificar Criterios de Exito del FASE file (plan/fases/FASE-{N}-*.md):

   • Leer seccion "Criterios de Exito"
   • Para cada criterio, verificar que la implementacion lo cumple
   • Documentar evidencia para cada criterio

3. Ejecutar suite completa de tests

4. Verificar coverage per-file (si el plan incluye Coverage Map §7.4):

   npx vitest run --coverage
   

   • Para cada source file en Coverage Map §7.4, verificar que tiene coverage > 0%
   • Para cada source file con tipo logic/entity/service/state-machine, verificar coverage >= 80% lines
   • Si un archivo tiene 0% y NO esta en Exclusions → FAIL — crear test task pendiente
   • Si un archivo tiene <80% y es lógica de dominio → WARN — reportar en completion

5. Reportar completion (incluir commit log):

FASE-0 Implementation Complete
================================
Total tasks: 12
Completed: 12 (100%)
Tests: 45 passing, 0 failing
Coverage: 92% lines (threshold: 80%)
  - Files below 80%: {list or "none"}
  - Files at 0% (not excluded): {list or "none"}
Criterios de Exito: 5/5 verified
Checkpoint: git tag fase-0-verified

Commit Log:
| Task | SHA | Message | Refs |
|------|-----|---------|------|
| TASK-F0-001 | abc1234 | chore(bootstrap): configure wrangler.toml | FASE-0 |
| TASK-F0-002 | def5678 | feat(bootstrap): initialize TypeScript project | FASE-0, ADR-001 |
| TASK-F0-003 | ghi9012 | feat(auth): add JWT authentication middleware | FASE-0, UC-002, ADR-003, INV-SYS-001 |
| ... | ... | ... | ... |

Commits: 12 atomic (abc1234..xyz9012)

Internal Phase Checkpoints

Checkpoints se crean automaticamente al completar todas las tasks de un phase interno:

Multi-Agent Strategy

Para tasks marcadas con [P] (paralelizables), se pueden lanzar agentes paralelos.

Parallel Execution Rules

1. Solo tasks marcadas [P] pueden ejecutarse en paralelo
2. Tasks paralelas NUNCA tocan los mismos archivos (garantizado por sdd-task-generator)
3. Cada agente ejecuta Phases 3-7 completas para su task
4. Cada agente marca su checkbox en Phase 7 (incluido en su commit atomico)
5. Si un agente falla, los demas continuan — el fallo se reporta al final
6. Los commits se crean secuencialmente (git no soporta commits paralelos)

Agent Instructions Template

You are a TASK IMPLEMENTER agent for sdd-task-implementer.

Your task: Implement {TASK-ID} from task/TASK-FASE-{N}.md

## Context
Read these files before coding:
- task/TASK-FASE-{N}.md (find your task entry)
- plan/PLAN-FASE-{N}.md (architecture decisions)
- {list of spec files from Refs field}
- spec/domain/01-GLOSSARY.md (ubiquitous language)

## Your Task
{Full task entry from task document}

## Process
1. Read acceptance criteria
2. Write failing tests
3. Implement code to pass tests
4. Run review checklist
5. Report results (do NOT commit — main agent commits)

## Constraints
- ONLY modify files listed in task entry
- ONLY implement what acceptance criteria require
- PAUSE if you find ambiguity or [DECISION PENDIENTE]
- Use ubiquitous language from glossary

Handling Pause Conditions

El implementer DEBE pausar y reportar al usuario en estas situaciones:

PAUSE: Ambiguity

PAUSE: Ambiguity in TASK-F0-005
  Spec ref: UC-005 paso 4
  Problem: "El sistema valida el formato" — no especifica que formatos son validos
  Options:
    A) Implementar validacion basica (extension + MIME type)
    B) Implementar validacion estricta (magic bytes + content inspection)
  Recommendation: A (sufficient per RN-181 timeout constraints)
  Action needed: User decision before continuing

PAUSE: Decision Pending

PAUSE: [DECISION PENDIENTE] found
  Location: spec/adr/ADR-025-rate-limiting.md line 45
  Content: "[DECISION PENDIENTE] Algoritmo de rate limiting: token bucket vs sliding window"
  Impact: TASK-F0-004 cannot be implemented without this decision
  Action needed: Resolve decision in spec before continuing

PAUSE: Spec-Implementation Conflict

PAUSE: Conflict detected
  Task: TASK-F0-008
  Spec says: "POST /api/v1/extractions" (contracts/API-extraction.md)
  Plan says: "POST /api/v1/extract" (plan/PLAN-FASE-1.md)
  Action needed: Resolve conflict — spec takes precedence

PAUSE: Build Failure

PAUSE: Build failure after TASK-F0-006
  Error: Type 'string' is not assignable to type 'Email'
  Cause: Missing value object implementation (TASK-F0-005 dependency)
  Action needed: Verify TASK-F0-005 is complete

PAUSE: Test Failure Unexpected

PAUSE: Test regression after TASK-F0-009
  Failing test: tests/middleware/auth.test.ts:42
  Test was passing after TASK-F0-003
  Cause: TASK-F0-009 modified shared middleware chain
  Action needed: Review integration between F0-003 and F0-009

Implementation Feedback Protocol

Principle: "Code reveals specification flaws the same way testing reveals bugs" (spec-kit). The implementer NEVER modifies spec/, but it CAN generate structured feedback for sdd-req-change to process.

When a PAUSE condition reveals a spec-level issue (ambiguity, conflict, missing behavior, incorrect contract), the implementer generates a feedback file instead of only halting:

Feedback File: feedback/IMPL-FEEDBACK-FASE-{N}.md

One file per FASE, appended as issues are discovered during implementation.

# Implementation Feedback — FASE-{N}

> Generated by: sdd-task-implementer
> Date: YYYY-MM-DD
> Status: PENDING | PARTIALLY-RESOLVED | RESOLVED

## Issues

### IF-{FASE}-{SEQ}: {Short Title}

| Field              | Value |
|--------------------|-------|
| **ID**             | IF-{FASE}-{SEQ} |
| **Severity**       | BLOCKER | WARNING |
| **Task**           | TASK-F{N}-{SEQ} |
| **Affected Specs** | {comma-separated spec file paths} |
| **Category**       | AMBIGUITY | CONFLICT | MISSING-BEHAVIOR | INCORRECT-CONTRACT | STALE-DECISION |
| **Status**         | OPEN | RESOLVED | WONT-FIX |

**Problem:**
> {Detailed description of what the implementer found}

**Evidence:**
> {Code context, test failure, or concrete example showing the issue}

**Suggested Resolution:**
> {Implementer's recommendation — e.g., "UC-005 should define valid formats as PDF, DOCX, TXT"}

**Workaround (if WARNING):**
> {How the implementer proceeded despite the issue, or "N/A — BLOCKER"}

---

Feedback Workflow

1. On PAUSE — evaluate if the issue is spec-level or implementation-level
2. If spec-level — append entry to feedback/IMPL-FEEDBACK-FASE-{N}.md (create file if first issue)
3. If BLOCKER — mark the task as [!] (blocked) and skip to next non-dependent task
4. If WARNING — document workaround, proceed with implementation, flag for later reconciliation
5. Continue implementing non-blocked tasks while feedback is pending
6. At session end — include feedback summary in Implementation Session Report
7. Resolution — user runs sdd-req-change --file feedback/IMPL-FEEDBACK-FASE-{N}.md to process spec corrections

Output Artifacts (additions)

SWEBOK v4 §4.4.17 — Feedback Loop for Construction: Implementation discoveries feed back into specifications through a formal, traceable channel. The implementer documents; the change manager resolves. Separation of concerns preserved.

Verification Protocol (Mode: --verify)

Cuando se invoca con --verify, ejecuta verificacion sin escribir codigo:

Dimension 1: Completeness

Para cada task con [x]:

• Verificar que los archivos listados existen
• Verificar que el commit referenciado existe en git log
• Contar tasks completas vs totales

Dimension 2: Correctness

Para cada task completa:

• Verificar que cada criterio de aceptacion se cumple en el codigo
• Verificar que los tests existen y pasan
• Verificar que los invariantes referenciados estan implementados

Dimension 3: Coherence

• Verificar que el codigo sigue la arquitectura del plan/
• Verificar que los naming conventions siguen el glosario
• Verificar que no hay code smells obvios (archivos >500 lineas, funciones >50 lineas)

Verification Report:

FASE-0 Verification Report
===========================
Completeness: 10/12 tasks implemented (83%)
  Missing: TASK-F0-011, TASK-F0-012

Correctness: 10/10 implemented tasks pass verification
  TASK-F0-001: 3/3 acceptance criteria ✓
  TASK-F0-002: 2/2 acceptance criteria ✓
  ...

Coherence: 2 observations
  - src/middleware/auth.ts:45 — function 32 lines (OK, under 50)
  - src/services/extraction.ts — uses "job" instead of "Extraction" (glossary violation)

Overall: 83% complete, 1 coherence issue to fix

Revert & Recovery Strategies

Reverting a Single Task

Lee el campo Revert de la task:

Rollback to Checkpoint

# Rollback entire phase to last checkpoint
git revert --no-commit HEAD..fase-{N}-{phase}
git commit -m "revert: rollback to FASE-{N} {phase} checkpoint"

Handling Failed Implementation

Si una task no puede implementarse:

1. Revertir los cambios parciales de esta task
2. Marcar la task con [!] (blocked) en el task document
3. Documentar la razon del bloqueo
4. Continuar con la siguiente task no dependiente

Important Constraints

1. SIEMPRE leer specs antes de implementar — nunca implementar de memoria o suposicion
2. SIEMPRE escribir tests antes de implementacion (cuando aplica) — test-first es obligatorio
3. SIEMPRE usar el commit message exacto del campo Commit de la task
4. SIEMPRE ejecutar el review checklist antes de commitear
5. NUNCA modificar archivos en spec/ — son la fuente de verdad
6. NUNCA modificar archivos en plan/ — son artefactos derivados
7. NUNCA commitear secretos (.env, API keys, credenciales)
8. NUNCA implementar features no descritas en los criterios de aceptacion
9. NUNCA usar git add -A — stage solo archivos especificos de la task
10. NUNCA ignorar tests fallidos — corregir antes de continuar
11. NUNCA saltarse pause conditions — ambiguedad, conflictos y decisiones pendientes requieren input del usuario
12. SIEMPRE mantener el sistema en estado funcional despues de cada commit (SWEBOK §4.3.7)
13. SIEMPRE usar lenguaje ubicuo del glosario en todo el codigo

Error Recovery

Context Loading Protocol

What to Read (in order of priority)

Lazy Loading

No cargar TODOS los specs de golpe. Cargar P0-P3 siempre. Cargar P4-P8 solo cuando la task los referencia.

Integration with Tech Stack

Este skill NO prescribe un tech stack. Lee el stack del proyecto desde CLAUDE.md y plan/ARCHITECTURE.md.

Stack Detection

IF CLAUDE.md mentions "TypeScript" AND "Cloudflare Workers":
  → Test runner: vitest
  → Build: wrangler
  → Deploy: wrangler deploy
  → DB: D1 (SQLite migrations)
  → Queue: Cloudflare Queues

IF CLAUDE.md mentions "Python":
  → Test runner: pytest
  → Build: pip/poetry
  → Deploy: varies

IF plan/ARCHITECTURE.md exists:
  → Follow its project structure exactly

Common Patterns by Task Type

See references/construction-protocol.md for implementation patterns per task type (entity, endpoint, middleware, migration, service, test, config).

Output Format: Implementation Session Report

Al finalizar una sesion de implementacion:

## Implementation Session Report

**Date:** {YYYY-MM-DD}
**FASE:** {N}
**Tasks completed:** {list}
**Tasks remaining:** {count}

### Progress

| Task | Status | Tests | SHA | Commit Message |
|------|--------|-------|-----|----------------|
| TASK-F0-001 | ✓ Complete | 3/3 | abc1234 | chore(bootstrap): configure wrangler.toml |
| TASK-F0-002 | ✓ Complete | 5/5 | def5678 | feat(bootstrap): init TypeScript project |
| TASK-F0-003 | ⏸ Paused | 2/4 | — | — |
| TASK-F0-004 | ○ Pending | — | — | — |

### Pauses
- TASK-F0-003: [DECISION PENDIENTE] in ADR-025 line 45

### Next Steps
1. Resolve ADR-025 decision
2. Continue with TASK-F0-003
3. Then TASK-F0-004 (parallel with F0-005)

### Checkpoints
- `fase-0-setup` after TASK-F0-002

Persist Summary

After completing a FASE or a batch of tasks, update pipeline-state.json:

1. Read pipeline-state.json from project root (create if absent with default stage structure)
2. Set stages["task-implementer"].status = "done" (or "running" if more FASEs remain)
3. Set stages["task-implementer"].lastRun = current ISO-8601
4. Set stages["task-implementer"].summary:
   • artifacts: list of key files created/modified in src/ and tests/ with labels (e.g., {"file": "src/extraction/pdf-parser.ts", "label": "PDF Parser"})
   • metrics: { "tasks_completed": N, "tasks_remaining": N, "commits": N, "tests_passed": N, "tests_failed": N }
   • highlights: top 3-5 notable observations (e.g., "FASE-0 complete: 8/8 tasks", "All 24 tests passing")
   • nextStep: "Run /sdd-task-implementer --fase=N" (next FASE) or "Pipeline complete" (if last FASE)
   • generatedAt: current ISO-8601
5. Write updated pipeline-state.json
6. Display summary table to user (console output)

Source: noelserdna/claude-plugin-sdd — distributed by TomeVault.