sedd 0.1.7 → 0.1.9

package/README.md

@@ -18,6 +18,19 @@
 
 ---
 
+## Para que serve o SEDD?
+
+SEDD é ideal para:
+
+| Caso de Uso | Descrição |
+|-------------|-----------|
+| **Features** | Novas funcionalidades com requisitos claros |
+| **Projetos** | Projetos completos com múltiplas entregas |
+| **Investigação** | Análise de código existente com estimativas |
+| **Melhorias** | Refatorações e otimizações planejadas |
+
+---
+
 ## Quick Start
 
 ```bash
@@ -179,6 +192,123 @@ Criar migration de follow-up? [Y/n]
 | `/sedd.implement` | Executar tasks com checkpoints |
 | `/sedd.implement --all` | Executar tudo sem parar |
 | `/sedd.dashboard` | Ver status atual de migrations e tasks |
+| `/sedd.estimate` | Estimar prazo e complexidade antes de começar |
+| `/sedd.validate` | Validar implementação contra expectativa |
+
+---
+
+## Fluxo Completo de Uso
+
+O SEDD funciona em um ciclo de 4 etapas principais:
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│  ESTIMATE   │────▶│   SPECIFY   │────▶│   CLARIFY   │────▶│  IMPLEMENT  │
+│  (Opcional) │     │             │     │             │     │             │
+└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
+       │                                       │                   │
+       │                                       ▼                   ▼
+       │                              ┌─────────────┐     ┌─────────────┐
+       └──────────────────────────────│   CLARIFY   │◀────│  VALIDATE   │
+                                      │  (repeat)   │     │  (ao final) │
+                                      └─────────────┘     └─────────────┘
+```
+
+### 1. `/sedd.estimate` (Opcional - Antes de Começar)
+
+Analisa o projeto e gera estimativa de prazo:
+
+```
+📊 ESTIMATIVA
+
+Total:      16h
+Humano:     4h (25%)  ← Decisões, revisão, edge cases
+AI:         12h (75%) ← Boilerplate, implementação
+Complexidade: M (Medium)
+```
+
+### 2. `/sedd.specify` - Criar Especificação
+
+Cria a estrutura inicial da feature com:
+- spec.md (especificação)
+- interfaces.ts (tipos TypeScript)
+- ui-mockups/ (se for UI)
+
+### 3. `/sedd.clarify` - Clarificar e Gerar Tasks
+
+Este é o comando mais importante. Ele usa um **modo de discussão flexível**:
+
+```
+📝 Clarification Session - Migration 001
+
+Você pode explicar livremente o que precisa.
+Eu vou anotar tudo e fazer perguntas quando necessário.
+
+Comandos disponíveis:
+  continue  → Continuar explicando
+  pergunte  → AI faz próxima pergunta
+  tasks     → Gerar tasks e finalizar
+```
+
+#### Comandos Inline do Clarify
+
+| Comando | O que faz | Quando usar |
+|---------|-----------|-------------|
+| `continue` | Permite continuar explicando | Quando você tem mais contexto para adicionar |
+| `pergunte` | AI faz uma pergunta de clarificação | Quando quer que a AI identifique gaps |
+| `tasks` | Gera tasks.md e finaliza | Quando terminou de explicar tudo |
+
+**Exemplo de sessão:**
+
+```
+Você: Preciso de um toggle de dark mode que persista
+
+AI: ✓ Anotado. Comandos: continue | pergunte | tasks
+
+Você: continue
+
+AI: Ok, continue explicando...
+
+Você: Deve ficar na página de settings, não no header
+
+AI: ✓ Anotado: Toggle em settings, não no header
+
+Você: pergunte
+
+AI: Q1: Como deve ser a persistência?
+    A) localStorage (mais simples)
+    B) Banco de dados (sincroniza entre dispositivos)
+    C) Cookie (SSR-friendly)
+
+Você: B, banco de dados
+
+AI: ✓ Decisão registrada: Persistência no banco
+
+Você: tasks
+
+AI: ✅ Gerando 5 tasks...
+    📊 Coverage: 92% 🟢
+```
+
+### 4. `/sedd.implement` - Executar Tasks
+
+Executa as tasks geradas, com validação contra expectativa.
+
+### 5. `/sedd.validate` - Validar ao Final
+
+Após implementar, valida se a expectativa foi atendida:
+
+```
+🔍 VALIDAÇÃO
+
+Cobertura:    75% ████████████░░░░
+Tasks:        3/4 completadas
+Arquivos:     5 alterados (+180, -12)
+Gaps:         1 encontrado
+
+⚠️ Gap: "sessions" não coberto
+   Criar task de follow-up? [Y/n]
+```
 
 ---
 

package/commands/sedd.clarify.md

@@ -51,26 +51,67 @@ User runs `/sedd.clarify`
 - Every migration has tasks.md (generated at the end)
 - Tasks reference this migration ID
 
+⚠️ **ANNOTATE EVERYTHING - TUDO VIRA TASK**
+- Cada ponto do usuario → anotar como fonte de task
+- Cada sugestao da AI aceita → anotar como fonte de task
+- Cada decisao tomada → anotar implicacoes como fontes de task
+- Cada edge case levantado → anotar como fonte de task
+- Formato: **[TASK_SOURCE:{tipo}]** antes de cada ponto anotado
+- Tipos: user-req, ai-suggestion, decision, edge-case, constraint
+
 ## Workflow
 
-### Step 1: Capture Expected Outcome (FIRST - MANDATORY)
+### Step 1: Load Context PRIMEIRO
 
-**ANTES DE QUALQUER COISA**, pergunte ao usuário:
+Read from feature root:
+- spec.md (especialmente `## Expectation` e user stories)
+- interfaces.ts (entidades)
+- _meta.json (expectation do specify)
+- Previous migrations (if any)
 
-```
-🎯 Qual é sua EXPECTATIVA para esta clarificação?
+### Step 1.5: Suggest Expectations (PROACTIVE)
 
-O que você espera ter funcionando ao final desta migration?
-(Isso será usado para validar se as tasks cobrem seu objetivo)
-```
+Com base no contexto carregado, AI DEVE:
+
+1. Apresentar a expectativa original da spec:
+   > "Expectativa original (da spec): {quote}"
+
+2. SUGERIR expectativas adicionais para esta migration baseado em:
+   - User stories nao cobertas por migrations anteriores
+   - Edge cases identificados nas interfaces
+   - Dependencias entre entidades
+   - Potenciais problemas de performance/seguranca
+   - Gaps entre a expectativa original e o que ja foi implementado
+
+3. Apresentar assim:
+   ```
+   Com base na spec e no que ja temos, sugiro para esta migration:
+
+   DEVE:
+   - [sugestao 1 baseada na spec]
+   - [sugestao 2 baseada em edge case]
+   - [sugestao 3 baseada em dependencia]
+
+   NAO DEVE:
+   - [restricao identificada]
+
+   Potenciais que identifiquei:
+   - [concern 1]
+   - [concern 2]
+
+   Quer acrescentar algo? Quer que eu veja outro potencial?
+   ```
+
+4. Aguardar usuario confirmar, ajustar, ou adicionar
+5. SO ENTAO consolidar expectativa final (summary + must + mustNot)
 
 Save in `clarify.md` under `## Expected Outcome` section (NO TOPO).
 
-**NÃO PROSSIGA** sem a expectativa do usuário.
+**NÃO PROSSIGA** sem a expectativa do usuário confirmada.
 
-### Step 1.5: Detail MUST and MUST NOT (STRUCTURED EXPECTATION)
+### Step 2: Detail MUST and MUST NOT (STRUCTURED EXPECTATION)
 
-Após capturar o resumo da expectativa, detalhar com regras claras:
+Após consolidar as expectativas (originais + sugeridas + usuario), detalhar com regras claras:
 
 ```
 Agora vamos detalhar sua expectativa:
@@ -111,13 +152,6 @@ Save in `clarify.md` under `## Expectation Details`:
 }
 ```
 
-### Step 2: Load Context
-
-Read from feature root:
-- spec.md (especialmente a seção Expectation original)
-- interfaces.ts
-- Previous migrations (if any)
-
 ### Step 3: Create New Migration Folder
 
 Generate new migration folder:
@@ -199,9 +233,10 @@ When user provides information (not a command):
 "O sistema precisa suportar múltiplos tenants, cada um com suas próprias configurações..."
 
 **Key Points Extracted:**
-- Multi-tenant architecture required
-- Per-tenant configuration
-- Isolation between tenants
+- **[TASK_SOURCE:user-req]** Multi-tenant architecture required
+- **[TASK_SOURCE:user-req]** Per-tenant configuration
+- **[TASK_SOURCE:ai-suggestion]** Isolation strategy needs definition
+- **[TASK_SOURCE:edge-case]** Cross-tenant data leaks prevention
 
 ---
 ```
@@ -274,7 +309,14 @@ Proceed to Step 6 (Generate Tasks).
 
 ### Step 6: Generate tasks.md (After All Q&A Complete)
 
-Based on all decisions, create tasks:
+Ao gerar tasks, VARRER clarify.md por TODOS os `[TASK_SOURCE:*]` tags:
+- Cada tag com tipo `user-req` → task obrigatoria
+- Cada tag com tipo `ai-suggestion` (aceita) → task obrigatoria
+- Cada tag com tipo `decision` → task para implementar decisao
+- Cada tag com tipo `edge-case` → task de validacao/protecao
+- Cada tag com tipo `constraint` → task de teste negativo
+
+Based on all decisions and TASK_SOURCE tags, create tasks:
 
 ```markdown
 # Tasks - Migration 001

package/commands/sedd.estimate.md

@@ -0,0 +1,231 @@
+# /sedd.estimate - Estimate Task or Project Effort
+
+## Purpose
+
+Analyze a feature or project and generate a detailed effort estimation markdown, separating human vs AI effort with complexity ratings.
+
+## Trigger
+
+- `/sedd.estimate` - Estimate current feature
+- `/sedd.estimate "feature description"` - Estimate new demand
+- `/sedd.estimate --path src/components` - Investigate specific path
+
+## Pre-flight Checks
+
+1. **Load Configuration**
+   ```
+   Read sedd.config.json (or use defaults)
+   Default specsDir: .sedd
+   ```
+
+2. **Check Feature Context**
+   - If on feature branch: use that feature
+   - If spec.md exists: use existing specification
+   - If neither: ask for feature description
+
+3. **Verify SEDD is initialized**
+   - Check if specsDir exists
+   - If not: suggest `npx sedd init`
+
+## Workflow
+
+### Step 1: Gather Context
+
+**OBRIGATÓRIO:** Pergunte ao usuário:
+
+```
+📁 Para uma análise mais precisa, me envie o path do arquivo principal.
+
+💡 Dica: No seu editor de código, clique com botão direito no arquivo
+   e selecione "Copy Relative Path", depois cole aqui.
+
+Exemplo: src/components/Dashboard.tsx
+```
+
+### Step 2: Analyze Project Structure
+
+Investigate the codebase:
+- Read spec.md if exists
+- Read interfaces.ts if exists
+- Analyze related files from provided path
+- Identify patterns and dependencies
+- Find similar implementations
+
+### Step 3: Generate Task Breakdown
+
+For each identified task:
+
+```typescript
+{
+  taskId: "T001-001",
+  description: "Create ThemeContext",
+  humanHours: 1,      // Design decisions, reviews, edge cases
+  aiHours: 3,         // Boilerplate, patterns, implementation
+  confidence: 85,     // How confident in this estimate
+  complexity: "M",    // XS, S, M, L, XL
+  risks: ["May need refactoring if theme structure changes"]
+}
+```
+
+### Step 4: Calculate Totals
+
+```
+Total Hours = Sum of all task hours
+Human Hours = Sum of human-only effort
+AI Hours = Sum of AI-assisted effort
+Complexity = Weighted average of task complexities
+```
+
+**Complexity Mapping:**
+| Size | Hours Range | Description |
+|------|-------------|-------------|
+| XS | 1-2h | Trivial change, single file |
+| S | 2-4h | Simple feature, few files |
+| M | 4-8h | Medium feature, multiple files |
+| L | 8-16h | Large feature, architectural changes |
+| XL | 16h+ | Epic, multiple systems |
+
+### Step 5: Generate estimate.md
+
+Create `.sedd/{FEATURE}/estimate.md`:
+
+```markdown
+# Estimativa: {{FEATURE_NAME}}
+
+> Gerado: {{TIMESTAMP}}
+> Confiança Média: {{CONFIDENCE}}%
+
+## Resumo Executivo
+
+| Métrica | Valor |
+|---------|-------|
+| **Total Estimado** | {{TOTAL}}h |
+| **Esforço Humano** | {{HUMAN}}h |
+| **Esforço AI** | {{AI}}h |
+| **Complexidade** | {{COMPLEXITY}} |
+
+### Distribuição de Esforço
+
+```
+Humano: ████████░░░░░░░░ 25%
+AI:     ████████████░░░░ 75%
+```
+
+---
+
+## Breakdown por Task
+
+| Task | Descrição | Humano | AI | Total | Confiança |
+|------|-----------|--------|-----|-------|-----------|
+| T001-001 | Create ThemeContext | 1h | 3h | 4h | 85% |
+| T001-002 | Add toggle component | 0.5h | 1.5h | 2h | 90% |
+| T001-003 | Persist preference | 1h | 2h | 3h | 75% |
+
+---
+
+## Análise de Contexto
+
+### Arquivos Analisados
+- `{{PATH}}` - Arquivo principal investigado
+- `src/related/file.ts` - Dependência identificada
+
+### Padrões Identificados
+- Usa Context API para estado global
+- Segue padrão de Repository para persistência
+
+### Riscos Identificados
+1. **Risco 1:** Descrição do risco e mitigação
+2. **Risco 2:** Descrição do risco e mitigação
+
+### Premissas
+- Assumes existing theme system can be extended
+- Assumes localStorage is acceptable for persistence
+
+---
+
+## Notas
+
+- Estimativas de AI assumem uso de ferramentas como Claude Code
+- Esforço humano inclui: revisão, decisões de design, edge cases
+- Esforço AI inclui: boilerplate, implementação de padrões, testes
+
+---
+
+## Próximos Passos
+
+1. `/sedd.specify` - Criar especificação formal (se não existir)
+2. `/sedd.clarify` - Detalhar requisitos e gerar tasks
+3. `/sedd.implement` - Executar implementação
+```
+
+### Step 6: Display Summary
+
+Show interactive summary:
+
+```
+📊 ESTIMATIVA GERADA
+
+┌─────────────────────────────────────┐
+│  Feature: Dark Mode Toggle          │
+├─────────────────────────────────────┤
+│  Total:      16h                    │
+│  Humano:     4h (25%)               │
+│  AI:         12h (75%)              │
+│  Complexidade: M (Medium)           │
+│  Confiança:  82%                    │
+└─────────────────────────────────────┘
+
+📁 Arquivo gerado: .sedd/024-dark-mode/estimate.md
+
+Deseja prosseguir para /sedd.clarify? [Y/n]
+```
+
+## Output
+
+1. **estimate.md** - Markdown com estimativa detalhada
+2. **_meta.json** - Atualizado com `lastEstimate` timestamp
+
+## Rules
+
+- SEMPRE pedir path do arquivo para investigação
+- SEMPRE separar esforço humano vs AI
+- NUNCA estimar sem analisar código existente
+- Confiança < 60% = destacar como incerto
+- Atualizar estimativa se spec.md mudar
+
+## CLI Alternative
+
+```bash
+# Estimate current feature
+sedd estimate
+
+# Estimate with specific path
+sedd estimate --path src/components/Theme.tsx
+
+# Estimate new demand
+sedd estimate --desc "Add dark mode support"
+```
+
+## Estimation Guidelines
+
+### Human Effort Includes:
+- Architecture decisions
+- Code review
+- Edge case handling
+- Integration testing
+- Documentation review
+- Debugging complex issues
+
+### AI Effort Includes:
+- Boilerplate code generation
+- Following established patterns
+- Unit test generation
+- Documentation generation
+- Refactoring similar code
+- Standard implementations
+
+### Confidence Levels:
+- **90-100%:** Well-understood, done before
+- **70-89%:** Familiar territory, some unknowns
+- **50-69%:** New area, significant unknowns
+- **Below 50%:** Highly uncertain, needs more investigation

package/commands/sedd.specify.md

@@ -20,7 +20,11 @@ User runs `/sedd.specify "feature description"` or `/sedd.specify` (interactive)
 
 3. **Check for existing feature branch**
    - If on feature branch (###-name): use existing feature
-   - If not: create new feature
+   - If on master/main or outra branch nao-feature:
+     1. Determinar proximo feature ID (buscar maior ###- nas branches + 1)
+     2. Criar branch `{id}-{nome}` com `git checkout -b {id}-{nome}`
+     3. Confirmar: "Criei a branch {id}-{nome} e ja estou nela"
+     4. SO ENTAO prosseguir com criacao da estrutura
 
 ## Configuration