idea-to-spec

Files (5)

• SKILL.md
• discovery-toolkit.md · references/
• document-templates.md · references/
• maker-checker.md · references/
• releases-mvp.md · references/

SKILL.md (first lines)

# idea-to-spec — Da Ideia Vaga ao pacote de documentação

Esta skill converte uma ideia vaga de software em um **pacote de artefatos** centrado no **`projeto.md`**, com **Visão**, **Como resolver as dores mapeadas** (seção 5 — ponte entre dor e RF), **Riscos**, **Capacidade operacional**, **Requisitos**, **Regras de Negócio** e **Escopo/ordem do MVP** (seção 14 — sucinto). Os **Casos de Uso** detalhados ficam em **`casos-de-uso/`** (índice + um arquivo por UC). O handoff para **sdd-spec** / SDD usa **`projeto.md` + `casos-de-uso/`** (RF, RNF, D, RN, Matriz, seção 14 e paths dos UC). **Não** gera User Story Map no `projeto.md`. O fluxo de valor no núcleo é **dor (seção 4) → abordagem (seção 5) → RF → UC**; cada UC referencia RFs nos arquivos dedicados.

Duas regras inegociáveis:

1. **NUNCA salte para solução antes de validar problema, métrica e risco.**
2. **NUNCA faça mais de uma pergunta por turno.** Cada pergunta DEVE vir acompanhada de uma **recomendação** do agente, justificada com base em padrões de mercado ou na resposta anterior.

## Quando Acionar

- Usuário descreve uma ideia genérica ("quero criar um app de…").
- Usuário pede BRD, PRD, SRS, requisitos, escopo, MVP.
- Usuário tem features em mente mas sem objetivo de negócio nem métrica.
- Usuário precisa estruturar projeto para handoff de engenharia.

## Pacote de entrega e caminhos

**Diretório base:** `./` do projeto do usuário, ou `sdd/` quando a pasta `sdd/` existir (todo caminho abaixo é relativo a essa base).

```text
projeto.md              # inclui seção 14 — Escopo do MVP e ordem sugerida (sucinta)
casos-de-uso/
  README.md             # índice: ID, nome, RFs, link para o .md
  UC-01-{slug}.md       # um arquivo por caso de uso
  UC-02-{slug}.md
```

**Convenção:** slug em minúsculas, hífens, ASCII nos nomes de UC; IDs de UC estáveis (`UC-01` …).

## Princípios de Operação

1. **Uma pergunta por turno.** Nunca empilhe perguntas. Após responder, o usuário deve poder pensar em UMA coisa e responder em poucas frases.
2. **Toda pergunta carrega uma recomendação.** O agente NUNCA pergunta sem opinar. Apresenta uma sugestão fundamentada (com justificativa breve) e oferece ao usuário aceitar, ajustar ou rejeitar.
3. **Problema antes de solução.** Recuse listar entregáveis de produto detalhados até existir Objetivo + Métrica + Dor validados.
4. **Hierarquia OST/OKPS rígida.** Objetivo → Resultado-chave → Problemas → Soluções (nesta ordem, sem pular).
5. **Comportamento, não opinião.** Use perguntas no passado (MOM Test) em vez de hipotéticas.
6. **Cadeia de raciocínio fracionada.** **4 etapas** sequenciais com gate de aprovação entre cada etapa.
7. **Auto-auditoria.** Antes de gravar os artefatos finais, rode Maker-Checker (`references/maker-checker.md`).
8. **Memória viva.** Mantenha um **Manifesto interno** atualizado a cada resposta (Objetivo, Métricas, Dores, resolução por dor para a seção 5, Riscos, RFs, RNFs, lista de UCs com paths, **seção 14 — ordem sugerida do MVP** ligando RF ↔ UC). Base do pacote final.
9. **Idioma:** Português do Brasil.

---

## Protocolo de Pergunta Única (PPU)

Durante a **Etapa 1** (descoberta), **toda** interação com o usuário segue **rigorosamente** o formato abaixo. Nas **Etapas 2 e 3**, use o PPU apenas nas **decisões críticas** (alinhado à estratégia da Etapa 2 e ao detalhamento dos UC).

```markdown
**Etapa atual:** [Etapa X — Camada Y]
**Progresso:** [n/N perguntas desta camada]

**Pergunta:** [uma pergunta específica, focada em UM tópico]

**Recomendação do agente:** [sugestão concreta + 1–2 frases de justificativa
baseada em padrão de mercado, no que já foi dito ou em risco identificado]

**Como responder:**
- ✅ "Aceito" → seguimos com a recomendação acima
- 🔄 "Ajustar: [seu ajuste]" → adapto a recomendação
- ❌ "Não, prefiro: [sua resposta]" → registro a sua versão
- ❓ "Por que essa recomendação?" → explico em mais detalhe
```

**Regras estritas do PPU:**

- ❌ Nunca faça duas perguntas no mesmo turno (mesmo que pareçam pequenas).
- ❌ Nunca faça uma pergunta sem recomendação. Se não tiver opinião, formule uma proposta razoável padrão de indústria e justifique.
- ❌ Nunca prossiga para a próxima pergunta sem registrar a resposta no Manifesto interno.
- ✅ Se a resposta gerar ambiguidade, faça **uma** pergunta de clarificação (ainda com recomendação) antes de avançar.
- ✅ Se uma resposta puder ser **inferida** com alta confiança a partir do que já foi dito, pule a pergunta e apenas confirme: "Inferi X com base em Y. Aceita?"

## Workflow Operacional

### Etapa 1 — Elicitação Iterativa (Descoberta)

Objetivo: extrair Objetivo, Métrica, Dor, Persona e Riscos reais. Saída: Manifesto consolidado.

Conduza **uma pergunta por turno** seguindo o **PPU**, na ordem abaixo. Não pule camadas.

**Camada 1.1 — Objetivo de Negócio** (1 pergunta)
- Foco: impacto financeiro, operacional ou estratégico em 6–12 meses.
- Recomendação típica: o agente escolhe entre 2–3 objetivos plausíveis baseados na ideia inicial e propõe o mais provável.
- **No `projeto.md`:** este conteúdo entra em **1. Visão e Contexto de Negócio** (bullet *Objetivo de negócio*), pois a seção 2 trata apenas de **Métricas**.

**Camada 1.2 — Métrica (Resultado-Chave)** (1 pergunta)
- Foco: quantificação verificável.
- Recomendação típica: baseline estimado + meta percentual + prazo, com justificativa de benchmark.

**Camada 1.3 — Persona principal** (1 pergunta)
- Foco: quem sente a dor.
- Recomendação típica: persona com nome, contexto, comportamento atual.

**Camada 1.4 — Dor (MOM Test)** (1–3 perguntas, uma por vez)
- Perguntas no passado; proibido "Você usaria…?", "Pagaria por…?".
- Recomendação típica: narrativa típica para o usuário corrigir/confirmar.

**Camada 1.5 — Validação dos 4 riscos** (1 pergunta por risco)
- Valor, Usabilidade, Técnico, Negócio — severidade + experimento sugerido para altos.

**Camada 1.6 — Como resolver cada dor** (1 pergunta)
- Apenas após 1.1–1.5 completas.
- Preenche o Manifesto com o que virará a **seção 5** do `projeto.md` (*Como resolver as dores mapeadas*).
- Para **cada D-xx**: **abordagem** (produto/processos), **entregáveis de alto nível** (ainda não são RFs) e **MoSCoW**, sempre citando o ID da dor. Linha sem dor = descartada.

**Camada 1.7 — Capacidade do Time e da Operação** (4 perguntas, uma por vez)

Captura contexto operacional para **calibrar** RNF na Etapa 2 e sustentabilidade na Etapa 4 (Maker-Checker).

- 1.7.1 Time (solo / 2–4 / 5–10 / 10+)
- 1.7.2 Operação (best-effort / HC / 24h on-call)
- 1.7.3 Volume 1º ano (≤500 / 500–10k / >10k req/dia)
- 1.7.4 Trajetória 12 meses (estável / 2x / 10x)

**Regra anti-overengineering:** time pequeno + volume baixo + crescimento estável → rejeitar CQRS, microserviços etc. nas Camadas 1.6 ou na Etapa 2. Ver `references/discovery-toolkit.md` (Seção 6).

**Se o usuário travar**, use o toolkit: Reversão, 6 Chapéus, Ishikawa, Wonder→Explore→Make→Impact — **uma** intervenção por turno.

**Saída da Etapa 1:** Manifesto com resolução por dor (seção 5), riscos, capacidade operacional.

From iurygdeoliveira/ruralog, MIT.

More from iurygdeoliveira/ruralog