Colliers × Costal — Interno

Runbook — Gestão de Tasks

Leitura de 7 min

Runbook | Gestão de Tasks

runbook governanca todo

Operação do sistema de tasks 1-task-1-nota com Base de pipeline. Fonte da verdade: 00-projeto/tasks/T-XXX.md (uma nota por task). Pipeline visual: _bases/tasks-pipeline.base (9 views — kanban, por owner, por frente, por prazo, sprint, completa, atrasadas, concluídas, dependências). Dashboard read-only: TASKS.md na raiz do vault — auto-gerado periodicamente, não editar.

📥 Criar nova task

Passo a passo

  1. Identificar próximo ID livre — abrir TASKS.md e ler “Próximo ID livre” no fim. Ou: ler 00-projeto/tasks/ e usar max(ID) + 1.
  2. Copiar template — cp 00-projeto/tasks/_template.md 00-projeto/tasks/T-XXX.md (ou via comando do Obsidian)
  3. Preencher frontmatter completo. Campos obrigatórios:
    • id: T-XXX
    • title: verbo no infinitivo, < 90 chars
    • status: aberta (default)
    • priority: critica / alta / media / baixa
    • owner: slug canônico do arquivo da pessoa em 00-projeto/directory/pessoas/<slug>.md (ex: pedro-villa, gabriel, antonio-pavanelli). Nunca slug curto. Exceções: axios, time-anouk.
    • frente: anouk-interno / anouk-cliente / costal / colliers / geral
    • created: data ISO de hoje
    • origem: ata / gap / dependencia / decisao / spec / definicao / manual
  4. Preencher body com:
    • Descrição clara (o que e por quê)
    • Critérios de conclusão com checkboxes verificáveis
    • Contexto / origem (link para ata, gap, etc.)
  5. Verificar na Base — abrir tasks-pipeline e conferir que a task aparece na coluna correta do kanban
  6. (Opcional) Regenerar dashboard — python 99-operacao/scripts/export-tasks-dashboard.py para atualizar TASKS.md

Convenção de IDs

  • IDs são sequenciais e persistentes — uma task descontinuada não libera o ID
  • Em caso de duas sessões em paralelo, fazer merge no fim do dia (sessão de consolidação de sexta)
  • Se houver colisão, registrar em changelog e remapear o ID conflitante

✏️ Atualizar status de uma task

Mudar para “em-progresso”

  1. Abrir nota T-XXX
  2. Editar frontmatter: 
    status: em-progresso
  3. Adicionar entrada em Histórico de status no body: 
    - **YYYY-MM-DD** — em progresso (motivo: <opcional>)

Marcar como concluída

  1. Editar frontmatter: 
    status: concluida
completed: 2026-04-30          # ISO
effort_real: 2.5               # horas (opcional)
  2. Marcar todos os critérios de conclusão como [x]
  3. Adicionar entrada em Histórico de status: 
    - **2026-04-30** — concluída. <breve resumo do entregável>

Bloquear / desbloquear

  1. Editar frontmatter: 
    status: bloqueada
depends_on: [T-XXX, T-YYY]   # IDs das tasks que bloqueiam (se aplicável)
  2. Documentar causa do bloqueio em Notas operacionais

Quando desbloquear: voltar para aberta ou em-progresso e atualizar histórico.

📋 Visualizações disponíveis

Pipeline (kanban) — uso diário

Abrir tasks-pipeline, view 🎯 Pipeline (kanban por status).

Colunas:

  • em-progresso (em curso agora)
  • bloqueada (atenção — destrancar)
  • aberta (próxima na fila)
  • pendente (esperando trigger)

Por owner — quem está fazendo o quê

View 👥 Por owner — agrupa cards pela pessoa responsável. Útil para 1:1 e alinhamento.

Por frente — atendimento por cliente

View 🏢 Por frente — separa Anouk-interno / Anouk-cliente / Costal / Colliers / Geral.

Por prazo — urgência

View 📅 Por prazo (urgência) — agrupa por prazo_tipo (hoje / esta-semana / curto / continua / etc.)

Sprint atual — semana 2

View 🚀 Sprint atual — só tasks da sprint vigente (filtra sprint.contains("semana-2")).

Para mudar de sprint: editar a Base e ajustar o filtro sprint.contains("semana-3"). Idealmente mudar 1× por semana.

Atrasadas + críticas — alerta operacional

View ⚠️ Atrasadas + Críticas — combina prazo passado OU priority: critica.

Concluídas — histórico

View ✅ Concluídas (histórico) — searchable, ordenado por data de conclusão DESC.

Dependências — risco operacional

View 🔗 Dependências — só tasks com depends_on ou blocks preenchidos. Ajuda a ver caminho crítico.

🔄 Manutenção periódica

Sexta-feira — sessão de consolidação semanal

  1. Abrir Base, view 🎯 Pipeline, conferir status de tudo
  2. Mover tasks completadas: status: concluida + completed: <data>
  3. Identificar atrasadas (view ⚠️ Atrasadas) e:
    • Replanejar prazo (atualizar prazo)
    • Bloquear (mudar para bloqueada + documentar causa)
    • Repriorizar (priority: critica se ficou urgente)
  4. Regenerar dashboard: python 99-operacao/scripts/export-tasks-dashboard.py
  5. Anunciar mudanças críticas no Slack

Mensalmente — limpeza

  1. Identificar tasks com status: pendente há > 30 dias — converter para cancelada ou re-priorizar
  2. Verificar effort_real preenchido em concluídas (calibração de estimativas futuras)
  3. Auditar IDs — não deve haver lacunas inexplicadas

🛠️ Scripts disponíveis

Migração inicial (já executada uma vez)

python 99-operacao/scripts/migrate-tasks-to-notes.py
  • Lê TASKS.md (formato antigo de tabela) e gera 1 nota por task
  • Idempotente — re-executar sobrescreve as notas com base no estado atual de TASKS.md

Export do dashboard

python 99-operacao/scripts/export-tasks-dashboard.py
  • Lê todas as notas em 00-projeto/tasks/T-*.md
  • Gera TASKS.md na raiz como dashboard read-only
  • Inclui: resumo executivo · críticas · atrasadas · em progresso · bloqueadas · todas ativas · concluídas · próximo ID

Quando rodar:

  • Após sessão de consolidação semanal (sexta)
  • Após criar/concluir 5+ tasks num dia
  • Manualmente sempre que quiser visão consolidada fresca

Validação (a implementar)

python 99-operacao/scripts/validate-tasks.py    # TODO

Sanity-checks: IDs duplicados · owners inválidos · prazos malformados · dependências circulares · campos obrigatórios faltando.

🧪 Convenções de sintaxe Obsidian Bases

Aprendidas no debug de 27/04 com tasks-pipeline.base. Registrar aqui para qualquer Base nova do vault evitar o caminho de erro.

✅ Funciona

SintaxeUso
file.folder.startsWith("path")Filtrar por pasta — preferir startsWith em vez de ==
file.name != "_template"Excluir template ou folder note
file.content.contains("texto")Buscar texto só no body (não inclui frontmatter)
status == "aberta"Acesso direto a propriedade do frontmatter — funciona em filter de view
owner == "pedro"Idem
priority == "critica"Idem
sprint.contains("semana-2").contains() em propriedade string do frontmatter
prazo_tipo == "hoje" or prazo_tipo == "imediato"Operador or inline
Propriedades em order: (ex: title, owner, status)Renderiza coluna na tabela
Propriedades em sort:Ordena pela propriedade

❌ Não funciona / a evitar

SintaxeErro / motivo
file.extension == "md"extension não existe no tipo File — remover
file.content.contains("status: aberta")file.content não inclui frontmatter — usa só o body
type: cardsNão suportado
groupBy: statusNão suportado
formulas:Não suportado
properties: { displayName: ... } no nível raizNão suportado
Strings com : sem aspasprazo_tipo: hoje é interpretado como nested mapping — envolver em 'aspas simples'
Wikilinks [[arquivo.base]] sem extensãoObsidian busca .md por default — usar [[arquivo.base|alias]] explícito
Wikilinks [[a|b]] em tabela markdownPipe quebra célula — escapar [[a|b]]

Padrão de filter para propriedade do frontmatter

- type: table
  name: Em progresso
  filters:
    and:
      - status == "em-progresso"
  order:
    - file.name      # mostra T-XXX
    - title          # mostra título
    - owner
    - prazo
    - priority
  sort:
    - property: priority
      direction: ASC

Padrão de filter combinado

filters:
  and:
    - frente == "colliers"
    - status != "concluida"
    - status != "cancelada"
    - prazo_tipo == "hoje" or prazo_tipo == "esta-semana"  # OR inline OK

🚨 Troubleshooting

”A Base não mostra a task que acabei de criar”

  • Verificar se o arquivo está em 00-projeto/tasks/ (não em subpasta)
  • Verificar se nome do arquivo é T-XXX.md (com prefixo correto)
  • Verificar se frontmatter abre com --- na primeira linha
  • Esperar 1-2 segundos pelo refresh do Obsidian (ou Cmd+R no Mac)

“Owner aparece como ‘undefined’ ou nome estranho”

  • Owner deve ser slug canônico do arquivo da pessoa em 00-projeto/directory/pessoas/<slug>.md
  • Use pedro-villa (não pedro), antonio-pavanelli (não antonio), igor-reginato (não igor), etc.
  • Para normalizar tasks com slugs curtos antigos: python 99-operacao/scripts/normalize-task-owners.py (idempotente)
  • Para validar integridade referencial: python 99-operacao/scripts/validate-tasks.py (reporta tasks com owner inválido, pessoas sem teams, depends_on quebrados)

“TASKS.md continua com formato antigo após eu editar nota”

  • TASKS.md é auto-gerado — você precisa rodar export-tasks-dashboard.py
  • Se mudar com frequência, considerar agendar via cron Axios (ver T-084)

“Quero deletar uma task para sempre”

  • Deletar arquivo T-XXX.md da pasta
  • ID não deve ser reutilizado — apenas marca uma lacuna (que é OK)
  • Documentar deleção em changelog se for relevante

🔮 Roadmap (sugestões para evoluir)

  • Cron Axios que roda export-tasks-dashboard.py automaticamente sex 13h30
  • Validador de IDs automático no commit hook
  • Gerador de templates para tasks com origem em ata (popula origem + refs)
  • Slack bot que cria task a partir de mensagem (Axios cron meeting-signals já faz isso parcialmente — ver agentes-core/axios/jobs/)
  • Exporter para CSV/Excel para reporting executivo
  • Dependency graph visualizer (Mermaid) a partir do depends_on/blocks

Ver também

Runbook criado em 2026-04-27 com a transição TASKS.md → notas individuais + Base.

Visão de gráfico

Backlinks