JantonioFC/skillsbank

/tc — Rastreador de Mudanças Técnicas

Dispatch um comando de TC (Mudança Técnica). Argumentos: $ARGUMENTS.

Se $ARGUMENTS estiver vazio, exiba este menu e pare:

/tc init                       Inicializa o rastreamento de TC neste projeto
/tc criar <nome>               Cria um novo registro de TC
/tc atualizar <tc-id> [...]    Atualiza campos, status, arquivos, transferência
/tc status [tc-id]             Mostra um TC ou o resumo do registro
/tc retomar <tc-id>            Retoma um TC de uma sessão anterior
/tc fechar <tc-id>             Transiciona um TC para implantado
/tc exportar                   Re-renderiza artefatos derivados
/tc dashboard                  Re-renderiza o resumo do registro

Caso contrário, parseie $ARGUMENTS como <subcomando> <restante> e encaminhe ao protocolo correspondente abaixo. Todos os scripts residem em engineering/tc-tracker/scripts/.

Subcomandos

init

1. Execute:

   python3 engineering/skills/tc-tracker/scripts/tc_init.py --root . --json
   

2. Se o status for already_initialized, reporte as estatísticas atuais e pare.
3. Caso contrário, informe o que foi criado e sugira /tc criar <nome> como próximo passo.

criar <nome>

1. Parseie <nome> como um slug em kebab-case. Se estiver faltando, peça ao usuário um.
2. Solicite ao usuário (uma pergunta de cada vez) por:
   • Título (5-120 caracteres)
   • Escopo: feature | bugfix | refactor | infrastructure | documentation | hotfix | enhancement
   • Prioridade: critical | high | medium | low (padrão medium)
   • Resumo (10+ caracteres)
   • Motivação
3. Execute:

   python3 engineering/skills/tc-tracker/scripts/tc_create.py --root . \
     --name "<slug>" --title "<título>" --scope <escopo> --priority <prioridade> \
     --summary "<resumo>" --motivation "<motivação>" --json
   

4. Reporte o novo ID do TC e o caminho para o registro.

atualizar <tc-id> [intenção]

1. Se <tc-id> estiver faltando, liste os TCs ativos (status in_progress ou blocked) de tc_status.py --all e pergunte qual.
2. Determine a intenção do usuário a partir da linguagem natural:
   • Mudança de status → --set-status <estado> com --reason "<porquê>"
   • Adicionar arquivos → um ou mais --add-file caminho[:ação]
   • Adicionar um teste → --add-test "<título>" --test-procedure "<passo>" --test-expected "<resultado>"
   • Atualizar transferência → qualquer combinação de --handoff-progress, --handoff-next, --handoff-blocker, --handoff-context
   • Adicionar uma nota → --note "<texto>"
   • Adicionar uma tag → --tag <tag>
3. Execute:

   python3 engineering/skills/tc-tracker/scripts/tc_update.py --root . --tc-id <tc-id> [flags] --json
   

4. Se o código de saída for diferente de zero, exiba o erro literalmente. A máquina de estados e o validador rejeitarão movimentos inválidos — não tente novamente cegamente.

status [tc-id]

• Se <tc-id> for fornecido:

  python3 engineering/skills/tc-tracker/scripts/tc_status.py --root . --tc-id <tc-id>
  

• Caso contrário:

  python3 engineering/skills/tc-tracker/scripts/tc_status.py --root . --all
  

retomar <tc-id>

1. Execute:

   python3 engineering/skills/tc-tracker/scripts/tc_status.py --root . --tc-id <tc-id> --json
   

2. Exiba o bloco de transferência de forma proeminente: progress_summary, next_steps (numerados), blockers, key_context.
3. Pergunte: "Retomar e continuar a partir do próximo passo 1? (s/n)"
4. Se sim, execute uma atualização para registrar a retomada:

   python3 engineering/skills/tc-tracker/scripts/tc_update.py --root . --tc-id <tc-id> \
     --note "Sessão retomada" --reason "transferência de sessão"
   

5. Comece a executar o primeiro item em next_steps. NÃO re-derive o contexto — confie na transferência.

fechar <tc-id>

1. Leia o registro via tc_status.py --tc-id <tc-id> --json.
2. Verifique se o status atual é tested. Se não, recuse e informe ao usuário quais transições ainda são necessárias.
3. Verifique test_cases: avise se algum estiver pending, fail ou blocked.
4. Pergunte ao usuário:
   • "Quem está aprovando? (seu nome, ou 'self')"
   • "Notas de aprovação (opcional):"
   • "Status da cobertura de testes: none / partial / full"
5. Execute:

   python3 engineering/skills/tc-tracker/scripts/tc_update.py --root . --tc-id <tc-id> \
     --set-status deployed --reason "Aprovado por <aprovador>" --note "Aprovação: <aprovador> — <notas>"
   

   Em seguida, edite diretamente o bloco de approval por meio de uma atualização subsequente se sua versão do script suportar; caso contrário, instrua o usuário a registrar a aprovação em notes.
6. Reporte: "TC-NNN fechado e implantado."

exportar

Não há exportação HTML automática nesta skill. Em vez disso, revalide tudo:

1. Leia o registro.
2. Para cada registro, execute:

   python3 engineering/skills/tc-tracker/scripts/tc_validator.py --record <caminho> --json
   

3. Execute:

   python3 engineering/skills/tc-tracker/scripts/tc_validator.py --registry docs/TC/tc_registry.json --json
   

4. Reporte: total de registros validados, quaisquer erros, caminhos para algo inválido.

dashboard

Execute o resumo de todos os registros:

python3 engineering/skills/tc-tracker/scripts/tc_status.py --root . --all

Regras de Ferro

1. Nunca edite tc_record.json manualmente. Sempre use tc_update.py para que o histórico de revisão seja anexado e a validação seja executada.
2. Nunca pule a máquina de estados. Avance pelos estados mesmo que pareça redundante.
3. Nunca exclua um TC. O histórico é somente de acréscimo — adicione uma revisão final e marque-a como [CANCELLED].
4. Manutenção de registro em segundo plano. Quando estiver no meio de uma tarefa, inicie um subagente em segundo plano para atualizar o TC. Não pare de codificar para fazer papelada.
5. Valide antes de relatar sucesso. Se um script sair com código não zero, exiba o erro e pare.

Skills Relacionadas

• engineering/tc-tracker — SKILL.md completo com referência de esquema, diagramas de ciclo de vida e o formato de transferência.
• engineering/changelog-generator — Emparelhe com o rastreador de TC: TCs para a trilha de auditoria por mudança, changelog para notas de versão voltadas ao usuário.
• engineering/tech-debt-tracker — Para rastrear dívidas de longo prazo, em vez de mudanças discretas de código.