tcc-docx-editor

Imported from GGHB0/pll_stability_9bus (.claude/skills/tcc-docx-editor/SKILL.md). Install upstream with npx skills add GGHB0/pll_stability_9bus --skill tcc-docx-editor. Copyright stays with the author.

Skill: tcc-docx-editor

Edita o TCC DOCX (config.py; hoje TCC_Victor_Bruno_V10.docx) no OOXML. Padrões fixos (Resumo↔Abstract + comentário, fechar/reabrir Word): padroes_revisao.md. Modo aceito pelo Victor: edições diretas no XML, sem tracked changes (helpers.py mantém os geradores com w:ins caso volte a ser necessário).

Fragmento externo (não o canônico) — ver fragmento_externo.md

Quando o alvo é um rascunho externo isolado (ex.: capitulos_4_5_revisados.docx, na pasta Fragmentos/ do TCC no OneDrive, plain-Normal-style, sem tracked changes/comentários/tabelas), o OOXML-surgery deste arquivo é overkill: usa-se python-docx direto, sem staging, sem repack.py, sem IDs a rastrear. Todo o workflow, as armadilhas (inserção de figura, renumeração, troca de termo, docPr duplicado, conferência de MD5) e as lições de redação estão em fragmento_externo.md. Ler antes de tocar num fragmento.

Para levar um fragmento para dentro do canônico, ver mesclagem_no_canonico.md: comparar as árvores de seção antes de trocar (o fragmento pode ser mais raso que o capítulo que substitui), mapear os títulos para Ttulo1–Ttulo4 ou eles somem do sumário, inverter a convenção de legenda, e reescalar as figuras da largura útil de origem para a de destino (o fragmento é Carta, 6,50 in; o TCC é A4, 6,30 in).

Cópia comentada externa (Oscar) — ver mesclagem_comentarios.md

Cópia do TCC com comentários novos do Oscar (não um rascunho de texto — ver "Fragmento externo" acima): mesclar só os comentários, sem as edições de texto soltas que vierem junto. Achar os novos por diff de texto e confirmar por data (não por ID, que o Word renumera) contra o comentário mais recente já no canônico, para não duplicar o que já foi mesclado com redação levemente diferente. Detalhe da mesclagem cirúrgica nas 4 partes XML de comentário em mesclagem_comentarios.md.

Revisão de português — ver revisao_pt.md

Passagem linguística separada das edições de conteúdo. scripts/check_pt.py varre o document.xml atrás das classes já vistas (regência capacidade … em, onde não locativo, através de, vírgula entre relativo e verbo, resíduo de LaTeX, duplo espaço, placeholder, em-dash). Não pega concordância, coesão nem frase sem verbo principal: isso só sai lendo o dump_blocks.py do corpo inteiro. Detalhes e falsos positivos em revisao_pt.md.

Formatação ABNT e paginação — skill tcc-abnt-layout

Passagem de forma (paginação, legendas, recuo, listas, equações), com verificadores e decisoes.md; o pipeline é o deste arquivo. Ilustração ou equação nova no canônico segue o padrão aplicado: legenda SEQ por tcc-abnt-layout/scripts/campos.py, tipo certo (Figura ou Tabela, D9) na legenda e na remissão, rótulo (N.M).

Convenções de escrita

• Nunca usar travessão/em-dash ("—") no texto do TCC. Reescrever com vírgula, ponto-e-vírgula, parênteses ou período. Vale para texto novo e para revisão: parágrafo editado com "—" perde o travessão na mesma edição.
• Não citar arquivo/script/variável de código no texto (params.m, nome.txt, VARIAVEL_MAIUSCULA) — usar termos de engenharia/modelagem. Nomes de bloco/subcircuito de esquemático (RESETI_I1, .SUB Clarke) são exceção. Ver feedback_docx_no_code_artifacts na memória.
• Conclusão (Cap. 6) sobe de altitude, não de profundidade: consolidação genérica do trabalho inteiro, nem parafraseando o "Resumo e conclusões" do capítulo de resultados nem aprofundando além dele. Percorrer o arco (contexto → teoria → método → síntese qualitativa) e fechar com contribuição, limites de validade e implicação prática — sobreposição literal zero com o resumo não basta, dá para dizer a mesma coisa. Ver tcc-conclusion-altitude na memória (2 versões recusadas em 2026-09-12).

Divisão de trabalho por modelo (3 níveis)

Regras de escalonamento

• Sessão rodando em Sonnet: fazer planejamento, conteúdo e scripting direto; delegar só o mecânico ao docx-runner. Nunca escalar para Opus por conta própria — se a tarefa parecer exigir síntese pesada, dizer isso ao usuário e deixar a troca de modelo com ele.
• Sessão rodando em Opus: usar Opus apenas para interpretar o pedido, redigir conteúdo novo e revisar/aprovar. O scripting desce para o agente docx-scripter (Sonnet) com uma spec precisa (blocos-alvo, strings old→new com counts esperados, conteúdo já redigido, IDs); o mecânico desce para o docx-runner (Haiku).
• Edição trivial (1–2 replaces óbvios): qualquer modelo faz direto, sem agente — o overhead de delegar não compensa.

Delegar via Agent tool (subagent_type: "docx-scripter" / "docx-runner"), com prompt autocontido: paths exatos, o que rodar, e qual é a "saída esperada" (para o agente saber quando abortar/perguntar).

Dependências

• config.py (nesta pasta) — paths pessoais (gitignored)
• helpers.py (nesta pasta) — geradores de parágrafo OOXML com w:ins
• scripts/ (nesta pasta) — utilitários fixos, todos python.exe <script> <args>:
  • dump_headings.py <xml> — mapa de títulos com índice de bloco
  • dump_blocks.py <xml> <ini> <fim> [--raw] — texto/XML de intervalo de blocos
  • find_text.py <xml> <padrão> [--regex] — ocorrências com bloco + contexto
  • check_ids.py <xml> — máximos de bookmark/ins/paraId + flag dirty do TOC
  • check_pt.py <xml> [--corpo N] — varredura de português (ver revisao_pt.md); rodar também sobre o XML de saída, antes do repack
  • repack.py <template.docx> <xml> <saida.docx> — injeta document.xml no ZIP
  • audit_docx.py <arquivo.docx> [--util-in N] — auditoria estrutural pré-entrega (comentários, bookmarks, campos, PAGEREF órfão, imagens, content-types, em-dash); sai com código 1 se algo falhou
  • word_finalize.ps1 -In <montado> -Out <final> [-Pdf <pdf>] [-Comments <json>] [-Replies <json>] — passa o DOCX pelo próprio Word: reconstrói o sumário, zera w:dirty e prova que o Word consegue salvar, não só abrir

Workflow padrão

1. STAGING (docx-runner): OneDrive → C:\Temp\tcc_edit.docx →
   extrair word/document.xml → C:\Temp\doc_tcc_edit.xml
   (guardar o **MD5** do DOCX no OneDrive p/ pré-check da entrega;
   timestamp e bytes não bastam, ver "Entrega" abaixo)
2. INSPEÇÃO (docx-runner): dump_headings / dump_blocks / find_text / check_ids
   (o estado real é o do XML recém-extraído; `content_map.md` pode estar
   desatualizado — ver "Notas críticas")
3. PLANO (principal): mapear blocos, redigir conteúdo, apresentar ao usuário
   e AGUARDAR APROVAÇÃO antes de editar
4. SCRIPT: escrever C:\Temp\gen_<tema>.py — ler doc_tcc_edit.xml, aplicar
   edits com counts verificados, sanity checks, gravar doc_tcc_<tema>.xml.
   Sessão em Sonnet → o próprio principal; sessão em Opus → docx-scripter
   via spec (o scripter também roda o script e a verificação, cobrindo o 5)
5. EXECUÇÃO (docx-runner): rodar o gen + dumps de verificação sobre a saída
6. REVISÃO (principal): conferir a saída dos checks
7. FINALIZAÇÃO: word_finalize.ps1 → audit_docx.py (tem que dar 0 falhas)
8. ENTREGA (docx-runner): Word fechado + sem lock `~$` → **MD5 do
   OneDrive igual ao do staging** → backup datado → cp → ls -la
9. KB (principal): atualizar docx_structure.md / historico_entregas.md /
   content_map.md / pendencias.md conforme o caso

Entrega (aprendido em 2026-09-02, na marra)

• Pré-check por MD5, não por timestamp/bytes (edição do usuário no Word pode manter o tamanho — foi o MD5 que pegou, numa entrega do fragmento, um save do Victor 8 min depois da minha cópia; entregar teria apagado o trabalho dele em silêncio).
• Backup datado antes de sobrescrever, sempre: <nome>_backup_YYYYMMDD_HHMMSS.docx em _backups/<versão>/ ao lado do arquivo (comentado/_backups/V10/).
• Conferir que o Word está fechado (tasklist | grep -i winword) e sem lock ~$* na pasta — trocar os bytes por baixo de uma sessão viva quebra o sincronismo do OneDrive ("CARREGAMENTO BLOQUEADO", upload recusado).
• Nunca entregar um zip montado à mão direto: rodar word_finalize.ps1 antes — o zip à mão abre e até exporta PDF, mas o w:dirty do sumário deixa o documento modificado ao abrir, disparando o mesmo bloqueio, e os PAGEREF de seções removidas ficam "Erro! Indicador não definido".
• audit_docx.py distingue "arquivo corrompido" de "problema de sincronismo": 0 falhas quando o Word reclamar = conteúdo são, problema é de upload.

Notas críticas

• VFS isolation: o python.exe do Windows NÃO acessa /c/Users/victo/AppData/Roaming/Claude/... (VFS do Claude Desktop). Trabalhar sempre com arquivos em C:\Temp\ ou no repositório.
• OneDrive lock: nunca editar no path do OneDrive; copiar para C:\Temp. A cópia de VOLTA falha se o documento estiver aberto no Word ("Device or resource busy") — pedir para fechar antes da entrega.
• Word renumera IDs ao salvar: se o usuário salvou o DOCX no Word, o registro de IDs do KB fica obsoleto — rodar check_ids.py no XML recém- extraído antes de inserir qualquer elemento novo.
• paraId: máximo 0x7FFFFFFF; prefixos A–F estouram. Usar 1FB0xxxx (sequência registrada no KB) e conferir colisão com grep antes.
• PowerShell + python -c inline quebra com regex [...] — escrever script em arquivo e rodar o arquivo.
• Sumário (TOC): texto das entradas fica em cache no XML — um replace de título espera 2 ocorrências (título real + cache), e o campo precisa de w:dirty="true" para o Word reconstruir ao abrir.
• Delta de contagem em substituição: trocar 1 bloco por N parágrafos dá <w:p +(N-1), não +N — errar isso faz o docx-scripter abortar (corretamente); conferir a aritmética antes de mandar a spec.
• Grep com classe de caracteres acentuada não casa (invers[ãa]o etc. retornam zero em locale C, multibyte quebrado dentro do [...]): repetir com padrão literal antes de concluir ausência. grep -c casa substring ("ISE" deu 12 ocorrências, todas "LISERRE"): usar -w ou ver o contexto.
• KB de conteúdo pode mentir sobre o que já foi escrito (content_map.md dava o Cap. 6 como redigido com o capítulo vazio no arquivo vivo): confirmar no XML recém-extraído antes de julgar/editar, corrigir o KB no passo 9.
• gen_*.py: todo replace com count esperado explícito (falhar se divergir); ET.fromstring no resultado antes de gravar; UTF-8 no stdout com sys.stdout.reconfigure(encoding='utf-8', errors='replace'), não io.TextIOWrapper(sys.stdout.buffer, ...) — dois módulos que se importam e fazem isso cada um por si fecham o buffer compartilhado ao ser coletado o primeiro wrapper (ValueError: I/O operation on closed file), achado ao escrever build_plan.py + gen_oscar_cap5_comments.py em 2026-09-29.

Referência de IDs e armadilhas XML

Ver .claude/kb/tcc-word/docx/docx_structure.md — registro de IDs usados/próximos e "Armadilhas de edição XML" (sectPr final via rindex, falso positivo <w:p vs <w:pgSz, etc.). Histórico de entregas: historico_entregas.md.