spec-first-copilot 0.7.0-beta.1 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +252 -167
- package/bin/cli.js +70 -70
- package/lib/init.js +92 -92
- package/lib/update.js +132 -132
- package/package.json +1 -1
- package/templates/.ai/memory/napkin.md +68 -68
- package/templates/.github/CHANGELOG.md +560 -533
- package/templates/.github/adapters/SETUP.md +314 -314
- package/templates/.github/adapters/confluence.md +295 -295
- package/templates/.github/adapters/errors.md +234 -234
- package/templates/.github/adapters/filesystem.md +353 -353
- package/templates/.github/adapters/interface.md +301 -301
- package/templates/.github/adapters/naming.md +241 -241
- package/templates/.github/adapters/registry.md +244 -244
- package/templates/.github/agents/backend-coder.md +215 -215
- package/templates/.github/agents/db-coder.md +165 -165
- package/templates/.github/agents/doc-writer.md +66 -66
- package/templates/.github/agents/frontend-coder.md +222 -222
- package/templates/.github/agents/infra-coder.md +341 -341
- package/templates/.github/agents/reviewer.md +99 -99
- package/templates/.github/agents/security-reviewer.md +153 -153
- package/templates/.github/copilot-instructions.md +272 -272
- package/templates/.github/instructions/docs.instructions.md +147 -145
- package/templates/.github/instructions/sensitive-files.instructions.md +32 -32
- package/templates/.github/rules.md +229 -229
- package/templates/.github/scripts/bootstrap-confluence.js +289 -289
- package/templates/.github/skills/sf-design/SKILL.md +161 -161
- package/templates/.github/skills/sf-dev/SKILL.md +204 -204
- package/templates/.github/skills/sf-discovery/SKILL.md +415 -415
- package/templates/.github/skills/sf-extract/SKILL.md +225 -225
- package/templates/.github/skills/sf-load/SKILL.md +296 -296
- package/templates/.github/skills/sf-mcp/SKILL.md +386 -386
- package/templates/.github/skills/sf-merge-docs/SKILL.md +152 -152
- package/templates/.github/skills/sf-plan/SKILL.md +152 -152
- package/templates/.github/skills/sf-publish/SKILL.md +144 -144
- package/templates/.github/skills/sf-session-finish/SKILL.md +93 -93
- package/templates/.github/skills/sf-start/SKILL.md +192 -192
- package/templates/.github/templates/estrutura/apiContracts.template.md +160 -159
- package/templates/.github/templates/estrutura/architecture.template.md +169 -168
- package/templates/.github/templates/estrutura/conventions.template.md +214 -212
- package/templates/.github/templates/estrutura/decisions.template.md +107 -107
- package/templates/.github/templates/estrutura/domain.template.md +161 -160
- package/templates/.github/templates/feature/PRD.template.md +279 -279
- package/templates/.github/templates/feature/Progresso.template.md +141 -141
- package/templates/.github/templates/feature/TRD.template.md +358 -358
- package/templates/.github/templates/feature/context.template.md +89 -89
- package/templates/.github/templates/feature/extract-log.template.md +49 -49
- package/templates/.github/templates/feature/projetos.template.yaml +79 -79
- package/templates/.github/templates/global/progresso_global.template.md +59 -57
- package/templates/.github/templates/specs/brief.template.md +66 -66
- package/templates/.github/templates/specs/contracts.template.md +147 -147
- package/templates/.github/templates/specs/scenarios.template.md +125 -125
- package/templates/.github/templates/specs/tasks.template.md +65 -65
- package/templates/_gitignore +35 -35
- package/templates/sfw.config.yml.example +147 -147
|
@@ -1,225 +1,225 @@
|
|
|
1
|
-
|
|
2
|
-
# /sf-extract $ARGUMENTS
|
|
3
|
-
|
|
4
|
-
Skill atômica de extração. Lê insumos brutos de `workspace/Input/$ARGUMENTS/` e gera **PRD e/ou TRD** conforme o conteúdo dos insumos.
|
|
5
|
-
`$ARGUMENTS` = nome do scope (ex: `app_barbearia`, `feat_cadastro_cliente`).
|
|
6
|
-
|
|
7
|
-
## Multi-agent
|
|
8
|
-
|
|
9
|
-
| Agente | Modelo | Papel |
|
|
10
|
-
|--------|--------|-------|
|
|
11
|
-
| **Reader** (1 por arquivo) | Sonnet | Lê e cataloga 1 arquivo. Não interpreta, apenas cataloga |
|
|
12
|
-
| **Produto-Analyzer** | Opus | Consolida conteúdo de produto → gera PRD (se aplicável) |
|
|
13
|
-
| **Tech-Analyzer** | Opus | Consolida conteúdo técnico → gera TRD (se aplicável) |
|
|
14
|
-
|
|
15
|
-
## Pré-condições
|
|
16
|
-
|
|
17
|
-
| # | Validação | Se falhar |
|
|
18
|
-
|---|-----------|-----------|
|
|
19
|
-
| 1 | `$ARGUMENTS` informado | Parar → "Informe o nome. Ex: /sf-extract feat_cadastro_cliente" |
|
|
20
|
-
| 2 | `workspace/Input/$ARGUMENTS/` existe com arquivos | Parar → "Pasta vazia. Rode /sf-load $ARGUMENTS ou coloque insumos manualmente" |
|
|
21
|
-
| 3 | `workspace/Output/$ARGUMENTS/.context.md` existe | Parar → "Execute /sf-start $ARGUMENTS primeiro" |
|
|
22
|
-
| 4 | Status é `discovery_done` ou `extract_done` | Se anterior → "Rode /sf-discovery primeiro". Se posterior → "Extração já aprovada. Edite .context.md pra re-extrair" |
|
|
23
|
-
|
|
24
|
-
## Passos
|
|
25
|
-
|
|
26
|
-
### 1. Carregar contexto
|
|
27
|
-
|
|
28
|
-
- `.context.md` → `first_run`, status
|
|
29
|
-
- `discovery.md` (obrigatório em v4) → análise profunda prévia dos insumos
|
|
30
|
-
- **`docs/` se existir** — usar como baseline pra responder checklist sem perguntar
|
|
31
|
-
- Templates:
|
|
32
|
-
- `.github/templates/feature/PRD.template.md`
|
|
33
|
-
- `.github/templates/feature/TRD.template.md`
|
|
34
|
-
- `.github/templates/feature/extract-log.template.md` (append-only)
|
|
35
|
-
|
|
36
|
-
### 2. Inventariar insumos
|
|
37
|
-
|
|
38
|
-
Para cada arquivo em `workspace/Input/$ARGUMENTS/` (ignorar `.gitkeep`):
|
|
39
|
-
- Calcular hash SHA-256 (primeiros 8 chars)
|
|
40
|
-
- Se `.extract-log.md` existe → classificar: NOVO / MODIFICADO / INALTERADO
|
|
41
|
-
- Se não existe → todos são NOVOS
|
|
42
|
-
|
|
43
|
-
### 3. Processar (Reader por arquivo, em paralelo)
|
|
44
|
-
|
|
45
|
-
Para cada arquivo NOVO ou MODIFICADO, Reader cataloga sem interpretar:
|
|
46
|
-
|
|
47
|
-
| Formato | O que extrair (cru) |
|
|
48
|
-
|---------|---------------------|
|
|
49
|
-
| .md, .txt | Parágrafos, listas, tabelas, qualquer menção a domínio/técnica |
|
|
50
|
-
| .sql | CREATE TABLE, constraints, índices, comentários, referências |
|
|
51
|
-
| .html | Campos, rotas, ações, permissões, estados (data-*) |
|
|
52
|
-
| .xml (drawio) | Fluxos, decisões, atores, sequências |
|
|
53
|
-
| .csv | Dados tabulares, mapeamentos |
|
|
54
|
-
| .png, .jpg, .pdf | Análise visual (wireframes, mockups) |
|
|
55
|
-
| Não identificado | Registrar NÃO IDENTIFICADO, gerar ambiguidade |
|
|
56
|
-
|
|
57
|
-
Reader devolve estrutura com **tudo que viu**, sem categorizar produto/tech.
|
|
58
|
-
|
|
59
|
-
### 4. Consolidar — decisão de quais docs gerar
|
|
60
|
-
|
|
61
|
-
Após todos os Readers, o skill decide:
|
|
62
|
-
|
|
63
|
-
- **Há conteúdo de produto?** (jornadas, atores, RNs, UX, telas)
|
|
64
|
-
- SIM → Produto-Analyzer gera PRD
|
|
65
|
-
- NÃO → PRD não é criado; `prd_existe = false` no `.context.md`
|
|
66
|
-
- **Há conteúdo técnico?** (stack, schema, endpoints, infra, segurança)
|
|
67
|
-
- SIM → Tech-Analyzer gera TRD
|
|
68
|
-
- NÃO → TRD não é criado; `trd_existe = false` no `.context.md`
|
|
69
|
-
|
|
70
|
-
**Ambos falsos** = extração falhou: erro "insumos sem conteúdo utilizável" + listar ambiguidade pedindo esclarecimento.
|
|
71
|
-
|
|
72
|
-
**Cenários típicos**:
|
|
73
|
-
- first-run de projeto novo com brief de produto + decisões técnicas → PRD + TRD (caso comum)
|
|
74
|
-
- bootstrap de infra (só docs técnicas) → só TRD
|
|
75
|
-
- feature de UX pura em projeto maduro (sem impacto técnico) → só PRD (raro)
|
|
76
|
-
|
|
77
|
-
### 5. Produto-Analyzer (se aplicável)
|
|
78
|
-
|
|
79
|
-
Gera PRD.md seguindo `templates/feature/PRD.template.md`:
|
|
80
|
-
|
|
81
|
-
- 13 seções fixas
|
|
82
|
-
- RNs com IDs estáveis (RN-001...)
|
|
83
|
-
- §11 Fora de Escopo: sugerir `/sf-start <nome>` pros itens (em vez de "backlog_extraido")
|
|
84
|
-
- §12 Ambiguidades: perguntas bloqueantes (o PM vai responder)
|
|
85
|
-
- §13 Rastreabilidade: de qual insumo veio cada seção
|
|
86
|
-
|
|
87
|
-
Antes de marcar ambiguidade, consultar `docs/domain.md` e `docs/conventions.md` —
|
|
88
|
-
se resposta já está lá, marcar "resolvido em docs/X §Y" em vez de perguntar.
|
|
89
|
-
|
|
90
|
-
### 6. Tech-Analyzer (se aplicável)
|
|
91
|
-
|
|
92
|
-
Gera TRD.md seguindo `templates/feature/TRD.template.md`:
|
|
93
|
-
|
|
94
|
-
- 11 seções fixas organizadas por área (§Sistema + §Área-X + transversais)
|
|
95
|
-
- GATEs SIM/NÃO por §Área: só preenche áreas que a feature toca
|
|
96
|
-
- §1 §Sistema é GATE=SIM sempre em first-run (baseline completo)
|
|
97
|
-
- ADRs em §9 (imutáveis após aceitas; sincronizadas em docs/decisions.md via /sf-merge-docs)
|
|
98
|
-
- §10 Ambiguidades técnicas: perguntas bloqueantes (o dev vai responder)
|
|
99
|
-
|
|
100
|
-
Antes de marcar ambiguidade, consultar `docs/architecture.md`, `docs/conventions.md`,
|
|
101
|
-
`docs/apiContracts.md`, `docs/decisions.md` — se resposta já está lá, marcar
|
|
102
|
-
"resolvido em docs/X §Y".
|
|
103
|
-
|
|
104
|
-
### 7. Checklist de temas críticos (FIXO)
|
|
105
|
-
|
|
106
|
-
Rodar sempre, após consulta a `docs/`. Temas não cobertos nem por insumos nem
|
|
107
|
-
por `docs/` viram ambiguidades — em PRD se é de produto, em TRD se é técnico:
|
|
108
|
-
|
|
109
|
-
| # | Tema | Doc destino se vazio | Texto da ambiguidade |
|
|
110
|
-
|---|------|---------------------|----------------------|
|
|
111
|
-
| 1 | Autenticação — mecanismo (JWT/OAuth/session) + operações protegidas | TRD §7.1 | "Mecanismo/escopo de auth não definido" |
|
|
112
|
-
| 2 | Autorização / Papéis — perfis, matriz, granularidade | TRD §7.2 | "Papéis e permissões não definidos" |
|
|
113
|
-
| 3 | Separação de serviços — mono/micro, API vs Worker vs Web | TRD §1.2 | "Arquitetura de serviços não definida" |
|
|
114
|
-
| 4 | Ambientes & deploy — dev/staging/prod, CI/CD | TRD §1.3-§1.4 e §5 | "Estratégia de ambientes não definida" |
|
|
115
|
-
| 5 | Dados sensíveis / LGPD | TRD §7.3 | "Tratamento de PII não mencionado" |
|
|
116
|
-
| 6 | Validações de entrada (schema) | TRD §2.3 | "Validações de schema não detalhadas" |
|
|
117
|
-
| 7 | Cenários de erro de produto | PRD §8 | "Cenários de erro não definidos" |
|
|
118
|
-
| 8 | Impacto em dados existentes (migração) | TRD §4.3 | "Impacto em dados existentes não avaliado" |
|
|
119
|
-
| 9 | Métricas de sucesso (produto) | PRD §9 | "Como medir sucesso desta feature?" |
|
|
120
|
-
|
|
121
|
-
> Analyzer NÃO inventa respostas. Se não está em insumo NEM em `docs/`, PERGUNTA.
|
|
122
|
-
> Em scope só-PRD ou só-TRD, temas fora do domínio correspondente são ignorados.
|
|
123
|
-
|
|
124
|
-
### 8. Gerar/atualizar `.extract-log.md`
|
|
125
|
-
|
|
126
|
-
```markdown
|
|
127
|
-
## Extração N — {{ISO_DATETIME}}
|
|
128
|
-
|
|
129
|
-
| Arquivo | Hash | Classificação | Status | Destino |
|
|
130
|
-
|---------|------|---------------|--------|---------|
|
|
131
|
-
| requisitos.md | a3f29c1d | NOVO | extraído | PRD §1, §3, §5 + TRD §2.1 |
|
|
132
|
-
```
|
|
133
|
-
|
|
134
|
-
Campo "Destino" mostra em qual doc (PRD/TRD) e em quais seções a info foi.
|
|
135
|
-
|
|
136
|
-
### 9. Atualizar `.context.md`
|
|
137
|
-
|
|
138
|
-
```yaml
|
|
139
|
-
status: "extract_done"
|
|
140
|
-
prd_existe: {{true|false}} # resultado do passo 4
|
|
141
|
-
trd_existe: {{true|false}} # resultado do passo 4
|
|
142
|
-
prd_aprovado: false # user vai aprovar manualmente
|
|
143
|
-
trd_aprovado: false # idem
|
|
144
|
-
ultima_skill: "/sf-extract"
|
|
145
|
-
atualizado_em: "{{ISO_DATETIME}}"
|
|
146
|
-
```
|
|
147
|
-
|
|
148
|
-
### 10. Publicar no backend (se `sfw.config.yml` existe)
|
|
149
|
-
|
|
150
|
-
Chamar `/sf-publish $ARGUMENTS PRD` (se `prd_existe=true`) e
|
|
151
|
-
`/sf-publish $ARGUMENTS TRD` (se `trd_existe=true`). Respeita `mode` de cada target.
|
|
152
|
-
Ver `.github/skills/sf-publish/SKILL.md`.
|
|
153
|
-
|
|
154
|
-
### 11. Saída obrigatória
|
|
155
|
-
|
|
156
|
-
```
|
|
157
|
-
/sf-extract $ARGUMENTS — completo
|
|
158
|
-
|
|
159
|
-
Artefatos locais:
|
|
160
|
-
- workspace/Output/$ARGUMENTS/PRD.md (gerado: {{true|false}})
|
|
161
|
-
- workspace/Output/$ARGUMENTS/TRD.md (gerado: {{true|false}})
|
|
162
|
-
- workspace/Output/$ARGUMENTS/.extract-log.md
|
|
163
|
-
|
|
164
|
-
Publish:
|
|
165
|
-
- {target-name}: PRD: {{status}} | TRD: {{status}}
|
|
166
|
-
OU
|
|
167
|
-
- SKIPPED (no sfw.config.yml) — projeto 100% local
|
|
168
|
-
|
|
169
|
-
Próximos passos:
|
|
170
|
-
1. [PM] Revise workspace/Output/$ARGUMENTS/PRD.md e aprove:
|
|
171
|
-
- Abra o arquivo, preencha §12 Ambiguidades (coluna "Resposta")
|
|
172
|
-
- Marque prd_aprovado=true em .context.md quando aprovar
|
|
173
|
-
(se PRD não foi gerado, pule)
|
|
174
|
-
|
|
175
|
-
2. [dev] Revise workspace/Output/$ARGUMENTS/TRD.md e aprove:
|
|
176
|
-
- Abra o arquivo, preencha §10 Ambiguidades técnicas
|
|
177
|
-
- Marque trd_aprovado=true em .context.md quando aprovar
|
|
178
|
-
(se TRD não foi gerado, pule)
|
|
179
|
-
|
|
180
|
-
3. Após aprovações relevantes: /sf-design $ARGUMENTS
|
|
181
|
-
```
|
|
182
|
-
|
|
183
|
-
Se `/sf-publish` retornou ERROR, a skill NÃO falha — apenas reporta. Artefato local salvo.
|
|
184
|
-
|
|
185
|
-
## Como responder ambiguidades (PRD §12 e TRD §10)
|
|
186
|
-
|
|
187
|
-
Mesma mecânica pros 2 docs. Quando `/sf-design` bloquear por ambiguidades pendentes:
|
|
188
|
-
|
|
189
|
-
1. Abrir `workspace/Output/$ARGUMENTS/PRD.md` (ou TRD.md)
|
|
190
|
-
2. Ir até §Ambiguidades (§12 no PRD, §10 no TRD)
|
|
191
|
-
3. Para cada linha sem resposta: preencher a coluna **`Resposta`** com texto objetivo
|
|
192
|
-
4. Salvar
|
|
193
|
-
5. Rodar `/sf-design $ARGUMENTS` novamente — gate vai passar
|
|
194
|
-
|
|
195
|
-
**Regras:**
|
|
196
|
-
- Resposta vazia ou `—` → ainda bloqueia
|
|
197
|
-
- Marcação `resolvido em docs/{arquivo} §{seção}` é gerada pelo Analyzer — não preencher manualmente
|
|
198
|
-
- Respostas são permanentes; não precisa repetir em re-extração
|
|
199
|
-
|
|
200
|
-
**Quando esse caminho não basta** (mudança estrutural grande — nova entidade, mudança
|
|
201
|
-
de escopo, contradição que exige novos insumos): adicionar arquivo de ajuste em
|
|
202
|
-
`workspace/Input/$ARGUMENTS/ajustes_v1.md` e rodar `/sf-extract` de novo. O hash detecta
|
|
203
|
-
NOVO → merge aditivo regenera PRD/TRD.
|
|
204
|
-
|
|
205
|
-
## Re-extração
|
|
206
|
-
|
|
207
|
-
- Merge ADITIVO com PRD/TRD existentes (nunca remove info de arquivos inalterados)
|
|
208
|
-
- Seções afetadas marcadas com `<!-- ATUALIZADO: re-extração ISO_DATE -->`
|
|
209
|
-
- Novos IDs (RN-NNN no PRD, ADR-NNN no TRD) continuam sequência
|
|
210
|
-
- Se PRD era inexistente e re-extração encontra produto → cria PRD agora
|
|
211
|
-
(`prd_existe` vira true; `prd_aprovado` volta pra false pra nova revisão)
|
|
212
|
-
- Idem pro TRD
|
|
213
|
-
|
|
214
|
-
## Erros
|
|
215
|
-
|
|
216
|
-
| Erro | Ação |
|
|
217
|
-
|------|------|
|
|
218
|
-
| Pasta vazia | Parar, listar formatos aceitos |
|
|
219
|
-
| `.context.md` não existe | Parar, sugerir `/sf-start $ARGUMENTS` |
|
|
220
|
-
| Status anterior a `discovery_done` | Parar → "/sf-discovery antes de /sf-extract" |
|
|
221
|
-
| Nenhum arquivo novo/modificado | Informar "Nenhuma alteração detectada" |
|
|
222
|
-
| Arquivo não identificado | Registrar no log, gerar ambiguidade |
|
|
223
|
-
| Contradição entre arquivos | Gerar ambiguidade citando os dois |
|
|
224
|
-
| `docs/` contradiz insumo | Ambiguidade especial: "insumo X diverge de docs/Y §Z — qual prevalece?" |
|
|
225
|
-
| Insumos não geram PRD NEM TRD | Erro "insumos sem conteúdo utilizável" + pedir esclarecimento |
|
|
1
|
+
|
|
2
|
+
# /sf-extract $ARGUMENTS
|
|
3
|
+
|
|
4
|
+
Skill atômica de extração. Lê insumos brutos de `workspace/Input/$ARGUMENTS/` e gera **PRD e/ou TRD** conforme o conteúdo dos insumos.
|
|
5
|
+
`$ARGUMENTS` = nome do scope (ex: `app_barbearia`, `feat_cadastro_cliente`).
|
|
6
|
+
|
|
7
|
+
## Multi-agent
|
|
8
|
+
|
|
9
|
+
| Agente | Modelo | Papel |
|
|
10
|
+
|--------|--------|-------|
|
|
11
|
+
| **Reader** (1 por arquivo) | Sonnet | Lê e cataloga 1 arquivo. Não interpreta, apenas cataloga |
|
|
12
|
+
| **Produto-Analyzer** | Opus | Consolida conteúdo de produto → gera PRD (se aplicável) |
|
|
13
|
+
| **Tech-Analyzer** | Opus | Consolida conteúdo técnico → gera TRD (se aplicável) |
|
|
14
|
+
|
|
15
|
+
## Pré-condições
|
|
16
|
+
|
|
17
|
+
| # | Validação | Se falhar |
|
|
18
|
+
|---|-----------|-----------|
|
|
19
|
+
| 1 | `$ARGUMENTS` informado | Parar → "Informe o nome. Ex: /sf-extract feat_cadastro_cliente" |
|
|
20
|
+
| 2 | `workspace/Input/$ARGUMENTS/` existe com arquivos | Parar → "Pasta vazia. Rode /sf-load $ARGUMENTS ou coloque insumos manualmente" |
|
|
21
|
+
| 3 | `workspace/Output/$ARGUMENTS/.context.md` existe | Parar → "Execute /sf-start $ARGUMENTS primeiro" |
|
|
22
|
+
| 4 | Status é `discovery_done` ou `extract_done` | Se anterior → "Rode /sf-discovery primeiro". Se posterior → "Extração já aprovada. Edite .context.md pra re-extrair" |
|
|
23
|
+
|
|
24
|
+
## Passos
|
|
25
|
+
|
|
26
|
+
### 1. Carregar contexto
|
|
27
|
+
|
|
28
|
+
- `.context.md` → `first_run`, status
|
|
29
|
+
- `discovery.md` (obrigatório em v4) → análise profunda prévia dos insumos
|
|
30
|
+
- **`docs/` se existir** — usar como baseline pra responder checklist sem perguntar
|
|
31
|
+
- Templates:
|
|
32
|
+
- `.github/templates/feature/PRD.template.md`
|
|
33
|
+
- `.github/templates/feature/TRD.template.md`
|
|
34
|
+
- `.github/templates/feature/extract-log.template.md` (append-only)
|
|
35
|
+
|
|
36
|
+
### 2. Inventariar insumos
|
|
37
|
+
|
|
38
|
+
Para cada arquivo em `workspace/Input/$ARGUMENTS/` (ignorar `.gitkeep`):
|
|
39
|
+
- Calcular hash SHA-256 (primeiros 8 chars)
|
|
40
|
+
- Se `.extract-log.md` existe → classificar: NOVO / MODIFICADO / INALTERADO
|
|
41
|
+
- Se não existe → todos são NOVOS
|
|
42
|
+
|
|
43
|
+
### 3. Processar (Reader por arquivo, em paralelo)
|
|
44
|
+
|
|
45
|
+
Para cada arquivo NOVO ou MODIFICADO, Reader cataloga sem interpretar:
|
|
46
|
+
|
|
47
|
+
| Formato | O que extrair (cru) |
|
|
48
|
+
|---------|---------------------|
|
|
49
|
+
| .md, .txt | Parágrafos, listas, tabelas, qualquer menção a domínio/técnica |
|
|
50
|
+
| .sql | CREATE TABLE, constraints, índices, comentários, referências |
|
|
51
|
+
| .html | Campos, rotas, ações, permissões, estados (data-*) |
|
|
52
|
+
| .xml (drawio) | Fluxos, decisões, atores, sequências |
|
|
53
|
+
| .csv | Dados tabulares, mapeamentos |
|
|
54
|
+
| .png, .jpg, .pdf | Análise visual (wireframes, mockups) |
|
|
55
|
+
| Não identificado | Registrar NÃO IDENTIFICADO, gerar ambiguidade |
|
|
56
|
+
|
|
57
|
+
Reader devolve estrutura com **tudo que viu**, sem categorizar produto/tech.
|
|
58
|
+
|
|
59
|
+
### 4. Consolidar — decisão de quais docs gerar
|
|
60
|
+
|
|
61
|
+
Após todos os Readers, o skill decide:
|
|
62
|
+
|
|
63
|
+
- **Há conteúdo de produto?** (jornadas, atores, RNs, UX, telas)
|
|
64
|
+
- SIM → Produto-Analyzer gera PRD
|
|
65
|
+
- NÃO → PRD não é criado; `prd_existe = false` no `.context.md`
|
|
66
|
+
- **Há conteúdo técnico?** (stack, schema, endpoints, infra, segurança)
|
|
67
|
+
- SIM → Tech-Analyzer gera TRD
|
|
68
|
+
- NÃO → TRD não é criado; `trd_existe = false` no `.context.md`
|
|
69
|
+
|
|
70
|
+
**Ambos falsos** = extração falhou: erro "insumos sem conteúdo utilizável" + listar ambiguidade pedindo esclarecimento.
|
|
71
|
+
|
|
72
|
+
**Cenários típicos**:
|
|
73
|
+
- first-run de projeto novo com brief de produto + decisões técnicas → PRD + TRD (caso comum)
|
|
74
|
+
- bootstrap de infra (só docs técnicas) → só TRD
|
|
75
|
+
- feature de UX pura em projeto maduro (sem impacto técnico) → só PRD (raro)
|
|
76
|
+
|
|
77
|
+
### 5. Produto-Analyzer (se aplicável)
|
|
78
|
+
|
|
79
|
+
Gera PRD.md seguindo `templates/feature/PRD.template.md`:
|
|
80
|
+
|
|
81
|
+
- 13 seções fixas
|
|
82
|
+
- RNs com IDs estáveis (RN-001...)
|
|
83
|
+
- §11 Fora de Escopo: sugerir `/sf-start <nome>` pros itens (em vez de "backlog_extraido")
|
|
84
|
+
- §12 Ambiguidades: perguntas bloqueantes (o PM vai responder)
|
|
85
|
+
- §13 Rastreabilidade: de qual insumo veio cada seção
|
|
86
|
+
|
|
87
|
+
Antes de marcar ambiguidade, consultar `docs/domain.md` e `docs/conventions.md` —
|
|
88
|
+
se resposta já está lá, marcar "resolvido em docs/X §Y" em vez de perguntar.
|
|
89
|
+
|
|
90
|
+
### 6. Tech-Analyzer (se aplicável)
|
|
91
|
+
|
|
92
|
+
Gera TRD.md seguindo `templates/feature/TRD.template.md`:
|
|
93
|
+
|
|
94
|
+
- 11 seções fixas organizadas por área (§Sistema + §Área-X + transversais)
|
|
95
|
+
- GATEs SIM/NÃO por §Área: só preenche áreas que a feature toca
|
|
96
|
+
- §1 §Sistema é GATE=SIM sempre em first-run (baseline completo)
|
|
97
|
+
- ADRs em §9 (imutáveis após aceitas; sincronizadas em docs/decisions.md via /sf-merge-docs)
|
|
98
|
+
- §10 Ambiguidades técnicas: perguntas bloqueantes (o dev vai responder)
|
|
99
|
+
|
|
100
|
+
Antes de marcar ambiguidade, consultar `docs/architecture.md`, `docs/conventions.md`,
|
|
101
|
+
`docs/apiContracts.md`, `docs/decisions.md` — se resposta já está lá, marcar
|
|
102
|
+
"resolvido em docs/X §Y".
|
|
103
|
+
|
|
104
|
+
### 7. Checklist de temas críticos (FIXO)
|
|
105
|
+
|
|
106
|
+
Rodar sempre, após consulta a `docs/`. Temas não cobertos nem por insumos nem
|
|
107
|
+
por `docs/` viram ambiguidades — em PRD se é de produto, em TRD se é técnico:
|
|
108
|
+
|
|
109
|
+
| # | Tema | Doc destino se vazio | Texto da ambiguidade |
|
|
110
|
+
|---|------|---------------------|----------------------|
|
|
111
|
+
| 1 | Autenticação — mecanismo (JWT/OAuth/session) + operações protegidas | TRD §7.1 | "Mecanismo/escopo de auth não definido" |
|
|
112
|
+
| 2 | Autorização / Papéis — perfis, matriz, granularidade | TRD §7.2 | "Papéis e permissões não definidos" |
|
|
113
|
+
| 3 | Separação de serviços — mono/micro, API vs Worker vs Web | TRD §1.2 | "Arquitetura de serviços não definida" |
|
|
114
|
+
| 4 | Ambientes & deploy — dev/staging/prod, CI/CD | TRD §1.3-§1.4 e §5 | "Estratégia de ambientes não definida" |
|
|
115
|
+
| 5 | Dados sensíveis / LGPD | TRD §7.3 | "Tratamento de PII não mencionado" |
|
|
116
|
+
| 6 | Validações de entrada (schema) | TRD §2.3 | "Validações de schema não detalhadas" |
|
|
117
|
+
| 7 | Cenários de erro de produto | PRD §8 | "Cenários de erro não definidos" |
|
|
118
|
+
| 8 | Impacto em dados existentes (migração) | TRD §4.3 | "Impacto em dados existentes não avaliado" |
|
|
119
|
+
| 9 | Métricas de sucesso (produto) | PRD §9 | "Como medir sucesso desta feature?" |
|
|
120
|
+
|
|
121
|
+
> Analyzer NÃO inventa respostas. Se não está em insumo NEM em `docs/`, PERGUNTA.
|
|
122
|
+
> Em scope só-PRD ou só-TRD, temas fora do domínio correspondente são ignorados.
|
|
123
|
+
|
|
124
|
+
### 8. Gerar/atualizar `.extract-log.md`
|
|
125
|
+
|
|
126
|
+
```markdown
|
|
127
|
+
## Extração N — {{ISO_DATETIME}}
|
|
128
|
+
|
|
129
|
+
| Arquivo | Hash | Classificação | Status | Destino |
|
|
130
|
+
|---------|------|---------------|--------|---------|
|
|
131
|
+
| requisitos.md | a3f29c1d | NOVO | extraído | PRD §1, §3, §5 + TRD §2.1 |
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Campo "Destino" mostra em qual doc (PRD/TRD) e em quais seções a info foi.
|
|
135
|
+
|
|
136
|
+
### 9. Atualizar `.context.md`
|
|
137
|
+
|
|
138
|
+
```yaml
|
|
139
|
+
status: "extract_done"
|
|
140
|
+
prd_existe: {{true|false}} # resultado do passo 4
|
|
141
|
+
trd_existe: {{true|false}} # resultado do passo 4
|
|
142
|
+
prd_aprovado: false # user vai aprovar manualmente
|
|
143
|
+
trd_aprovado: false # idem
|
|
144
|
+
ultima_skill: "/sf-extract"
|
|
145
|
+
atualizado_em: "{{ISO_DATETIME}}"
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
### 10. Publicar no backend (se `sfw.config.yml` existe)
|
|
149
|
+
|
|
150
|
+
Chamar `/sf-publish $ARGUMENTS PRD` (se `prd_existe=true`) e
|
|
151
|
+
`/sf-publish $ARGUMENTS TRD` (se `trd_existe=true`). Respeita `mode` de cada target.
|
|
152
|
+
Ver `.github/skills/sf-publish/SKILL.md`.
|
|
153
|
+
|
|
154
|
+
### 11. Saída obrigatória
|
|
155
|
+
|
|
156
|
+
```
|
|
157
|
+
/sf-extract $ARGUMENTS — completo
|
|
158
|
+
|
|
159
|
+
Artefatos locais:
|
|
160
|
+
- workspace/Output/$ARGUMENTS/PRD.md (gerado: {{true|false}})
|
|
161
|
+
- workspace/Output/$ARGUMENTS/TRD.md (gerado: {{true|false}})
|
|
162
|
+
- workspace/Output/$ARGUMENTS/.extract-log.md
|
|
163
|
+
|
|
164
|
+
Publish:
|
|
165
|
+
- {target-name}: PRD: {{status}} | TRD: {{status}}
|
|
166
|
+
OU
|
|
167
|
+
- SKIPPED (no sfw.config.yml) — projeto 100% local
|
|
168
|
+
|
|
169
|
+
Próximos passos:
|
|
170
|
+
1. [PM] Revise workspace/Output/$ARGUMENTS/PRD.md e aprove:
|
|
171
|
+
- Abra o arquivo, preencha §12 Ambiguidades (coluna "Resposta")
|
|
172
|
+
- Marque prd_aprovado=true em .context.md quando aprovar
|
|
173
|
+
(se PRD não foi gerado, pule)
|
|
174
|
+
|
|
175
|
+
2. [dev] Revise workspace/Output/$ARGUMENTS/TRD.md e aprove:
|
|
176
|
+
- Abra o arquivo, preencha §10 Ambiguidades técnicas
|
|
177
|
+
- Marque trd_aprovado=true em .context.md quando aprovar
|
|
178
|
+
(se TRD não foi gerado, pule)
|
|
179
|
+
|
|
180
|
+
3. Após aprovações relevantes: /sf-design $ARGUMENTS
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
Se `/sf-publish` retornou ERROR, a skill NÃO falha — apenas reporta. Artefato local salvo.
|
|
184
|
+
|
|
185
|
+
## Como responder ambiguidades (PRD §12 e TRD §10)
|
|
186
|
+
|
|
187
|
+
Mesma mecânica pros 2 docs. Quando `/sf-design` bloquear por ambiguidades pendentes:
|
|
188
|
+
|
|
189
|
+
1. Abrir `workspace/Output/$ARGUMENTS/PRD.md` (ou TRD.md)
|
|
190
|
+
2. Ir até §Ambiguidades (§12 no PRD, §10 no TRD)
|
|
191
|
+
3. Para cada linha sem resposta: preencher a coluna **`Resposta`** com texto objetivo
|
|
192
|
+
4. Salvar
|
|
193
|
+
5. Rodar `/sf-design $ARGUMENTS` novamente — gate vai passar
|
|
194
|
+
|
|
195
|
+
**Regras:**
|
|
196
|
+
- Resposta vazia ou `—` → ainda bloqueia
|
|
197
|
+
- Marcação `resolvido em docs/{arquivo} §{seção}` é gerada pelo Analyzer — não preencher manualmente
|
|
198
|
+
- Respostas são permanentes; não precisa repetir em re-extração
|
|
199
|
+
|
|
200
|
+
**Quando esse caminho não basta** (mudança estrutural grande — nova entidade, mudança
|
|
201
|
+
de escopo, contradição que exige novos insumos): adicionar arquivo de ajuste em
|
|
202
|
+
`workspace/Input/$ARGUMENTS/ajustes_v1.md` e rodar `/sf-extract` de novo. O hash detecta
|
|
203
|
+
NOVO → merge aditivo regenera PRD/TRD.
|
|
204
|
+
|
|
205
|
+
## Re-extração
|
|
206
|
+
|
|
207
|
+
- Merge ADITIVO com PRD/TRD existentes (nunca remove info de arquivos inalterados)
|
|
208
|
+
- Seções afetadas marcadas com `<!-- ATUALIZADO: re-extração ISO_DATE -->`
|
|
209
|
+
- Novos IDs (RN-NNN no PRD, ADR-NNN no TRD) continuam sequência
|
|
210
|
+
- Se PRD era inexistente e re-extração encontra produto → cria PRD agora
|
|
211
|
+
(`prd_existe` vira true; `prd_aprovado` volta pra false pra nova revisão)
|
|
212
|
+
- Idem pro TRD
|
|
213
|
+
|
|
214
|
+
## Erros
|
|
215
|
+
|
|
216
|
+
| Erro | Ação |
|
|
217
|
+
|------|------|
|
|
218
|
+
| Pasta vazia | Parar, listar formatos aceitos |
|
|
219
|
+
| `.context.md` não existe | Parar, sugerir `/sf-start $ARGUMENTS` |
|
|
220
|
+
| Status anterior a `discovery_done` | Parar → "/sf-discovery antes de /sf-extract" |
|
|
221
|
+
| Nenhum arquivo novo/modificado | Informar "Nenhuma alteração detectada" |
|
|
222
|
+
| Arquivo não identificado | Registrar no log, gerar ambiguidade |
|
|
223
|
+
| Contradição entre arquivos | Gerar ambiguidade citando os dois |
|
|
224
|
+
| `docs/` contradiz insumo | Ambiguidade especial: "insumo X diverge de docs/Y §Z — qual prevalece?" |
|
|
225
|
+
| Insumos não geram PRD NEM TRD | Erro "insumos sem conteúdo utilizável" + pedir esclarecimento |
|