spec-first-copilot 0.7.0 → 0.8.0-beta.2

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.
@@ -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 |