spec-writer

Spec Writer Skill

Criar SPECs tecnicas padronizadas para features, issues e refactors.

Docs Location (OBRIGATORIO)

Antes de salvar, resolver PROJECT_ROOT e validar:

PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
if [ "$PROJECT_ROOT" = "$HOME/Claude" ]; then
  # PARAR — estou no workspace raiz, nao em projeto. Perguntar qual projeto.
  exit 1
fi
DEST="$PROJECT_ROOT/docs/specs/{name}-spec.md"

NUNCA salvar em ~/Claude/docs/specs/ — hook docs-location-guard.sh bloqueia. Detalhes: ~/Claude/.claude/shared/patterns/docs-location.md.

Naming Convention

• Feature: $PROJECT_ROOT/docs/specs/{feature-name}-spec.md
• Issue: $PROJECT_ROOT/docs/specs/issue-{N}-spec.md
• Refactor: $PROJECT_ROOT/docs/specs/refactor-{scope}-spec.md

Template: SPEC Completa

# SPEC: [Titulo]

**Issue**: #N (se aplicavel)
**Author**: [nome]
**Date**: YYYY-MM-DD
**Status**: Draft | Review | Approved | Implemented

---

## 1. Objetivo

O que esta feature/fix resolve? Por que e necessario?
[1-3 frases claras]

## 2. Contexto

Situacao atual, problema, motivacao.
- Estado atual: [como funciona hoje]
- Problema: [o que esta errado ou faltando]
- Impacto: [quem e afetado e como]

## 3. Escopo

### In Scope
- Item 1
- Item 2
- Item 3

### Out of Scope
- Item A (motivo)
- Item B (sera feito na issue #M)

## 4. Requisitos Funcionais

### RF-01: [Nome do requisito]
**Descricao**: O sistema deve...
**Input**: [dados de entrada]
**Output**: [resultado esperado]
**Regras**:
- Regra 1
- Regra 2

### RF-02: [Nome do requisito]
...

## 5. Requisitos Nao-Funcionais

| ID | Requisito | Metrica | Target |
|----|-----------|---------|--------|
| RNF-01 | Performance | Response time | < 200ms p95 |
| RNF-02 | Disponibilidade | Uptime | 99.9% |
| RNF-03 | Seguranca | Auth required | All endpoints |
| RNF-04 | Acessibilidade | WCAG | Level AA |

## 6. Edge Cases

| # | Cenario | Comportamento Esperado |
|---|---------|----------------------|
| EC-01 | Input vazio | Mostrar mensagem de validacao |
| EC-02 | Timeout de API | Retry 3x com backoff, depois erro |
| EC-03 | Dados duplicados | Deduplicar silenciosamente |
| EC-04 | Permissao negada | Redirect para login |
| EC-05 | Dados inconsistentes | Log warning, usar fallback |

## 7. Criterios de Aceite

- [ ] CA-01: [criterio especifico e verificavel]
- [ ] CA-02: [criterio especifico e verificavel]
- [ ] CA-03: [criterio especifico e verificavel]
- [ ] CA-04: Todos os testes passam
- [ ] CA-05: TypeScript sem erros (`bun run typecheck`)
- [ ] CA-06: Lint sem warnings (`bun run lint`)
- [ ] CA-07: Code review aprovado

## 8. Dependencias

| Dependencia | Status | Responsavel |
|-------------|--------|-------------|
| API endpoint /foo | Done | Backend team |
| Design mockup | In Progress | UX team |
| Migration #123 | Pending | DBA |

## 9. Estimativa

| Fase | Esforco |
|------|---------|
| Implementacao | X horas |
| Testes | Y horas |
| Code review | Z horas |
| **Total** | **N horas** |

## 10. Notas Tecnicas

Decisoes de implementacao, trade-offs, riscos conhecidos.