# Plano: Painel OKR (Main Table) + cadência estratégica (inspiração operacional) Este documento une (1) a evolução da **visão OKR no Maestro** para um painel hierárquico inspirado em quadros tipo Monday e (2) um **modus operandi de ritos** (anual / trimestral / check-ins) como **orientação de uso**, com **alterações mínimas** no modelo de dados e no código existentes. --- ## 1. Princípios | Princípio | Implicação | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Flexibilidade** | Cadência (anual vs trimestral vs semanal) não é imposta por regras rígidas no banco; convenções e UX guiam o usuário. | | **Mínima mudança** | Continuar usando `strategy_objectives`, `strategy_key_results`, `strategy_key_result_links`, `project_kpis` e `StrategyService.getOKRs` / `getOKRContext`. Evitar novos motores de workflow na primeira entrega. | | **Separação clara** | **Direção estratégica** (tema do ano) ≠ **OKRs de execução** (tipicamente trimestre) ≠ **gestão** (check-in semanal/quinzenal) — refletido em **rótulos, filtros e conteúdo de apoio**, não obrigatoriamente em tabelas novas. | | **Compatibilidade** | Manter notas em [STRATEGY-OKR-COMPATIBILITY-NOTES.md](./STRATEGY-OKR-COMPATIBILITY-NOTES.md): OKR continua ortogonal ao X-Matrix; mesmos programas/projetos/KPIs de execução. | --- ## 2. Modus operandi (inspiração — não prescrição rígida) O arranjo sugerido evita dois extremos: ciclo longo demais (OKR decorativo) e ciclo curto demais (retrabalho e troca constante de prioridade). ### 2.1 Camadas de tempo (conceito) 1. **Ciclo anual** — Direção estratégica: prioridades do ano, temas centrais, limites e apostas. Não se detalha tudo; define-se o “norte”. 2. **Ciclo trimestral** — Melhor cadência para **OKRs em si**: tempo para resultado perceptível, testar hipóteses, corrigir rota, manter urgência. 3. **Rotina semanal ou quinzenal** — Gestão: acompanhar avanço, destravar, revisar **confiança** de entrega (check-in). ### 2.2 Fluxo de gestão (etapas 1–10, resumo) | Etapa | Foco | No Maestro (v1 sugerida) | | ------------------------------------ | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 — Preparação estratégica | 3–5 prioridades, riscos, indicadores que importam | Conteúdo em **manual / painel de ajuda / checklist estático** na tela OKR; opcionalmente campo texto em `strategy_objectives.description` ou notas futuras | | 2 — Objectives | Qualitativo, claro, poucos por área | Já coberto por `strategy_objectives` | | 3 — Key Results | Mensuráveis, 2–4 por objetivo | Já coberto por `strategy_key_results` | | 4 — Desdobramento / alinhamento | Áreas, dependências | Refletido em **links** a programas/projetos e KPIs; UI pode destacar conflitos só como informação | | 5 — Iniciativas | Depois de O + KR | **Projetos e ações** = entidades de execução já existentes (`projects`, atividades); painel liga KR → projeto → KPI | | 6 — Pactuação e comunicação | Papéis, medição, revisão | Dono: `owner_name` no objetivo; revisões = **ritmo humano** + lembretes fora do sistema na v1 | | 7 — Check-ins periódicos | Curto: status, tendência, bloqueio | **v1**: guia na UI + possível coluna “última atualização” de KR se já existir em dados; **v2 opcional**: tabela `okr_check_ins` ou campo `last_reviewed_at` em KR | | 8 — Mid-review (metade do trimestre) | Validade dos KR, contexto | **Documentação + lembrete**; sem obrigatoriedade no sistema | | 9 — Fechamento do ciclo | Lições, o que segue | **Export / relatório** ou campos de status de ciclo futuros | | 10 — Renovação | Próximo ciclo | Novo objetivo/ciclo no mesmo modelo | ### 2.3 Cadência recomendada na prática (referência) - **Anual**: revisar estratégia; temas prioritários do ano. - **Trimestral**: definir/revisar OKRs; alinhar áreas; pactuar iniciativas. - **Semanal**: check-in rápido dos KRs críticos. - **Mensal**: revisão executiva mais consolidada (rito organizacional). - **Fim do trimestre**: fechamento e lições aprendidas. **Modelo de equilíbrio citado:** estratégia anual + OKRs trimestrais + check-in semanal + review mensal + fechamento trimestral. --- ## 3. Mapeamento mínimo: cadência ↔ sistema atual Para **não** criar enums rígidos de “tipo de ciclo” na primeira entrega: | Necessidade | Abordagem flexível (preferida) | | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | Distinguir “ano” vs “trimestre” | Convenção no campo texto `**strategy_objectives.cycle`** (ex.: `FY2026`, `2026-Q1`, `2026-T1`). Filtros na UI por prefixo/padrão. | | Tema anual vs OKR trimestral | Objetivos com `cycle` anual vs objetivos com `cycle` trimestral; ou mesmo objetivo com descrição indicando camada. | | Check-in semanal/quinzenal | **Fora do schema na v1**: copy na UI, link para manual, opcional integração calendário depois. | | Governança (diretoria / gestores / times) | `owner_name` + futuros campos opcionais; ritos descritos no manual. | **Se no futuro for necessário:** colunas opcionais `cycle_tier` (`strategic_annual` `execution_quarterly`) ou tabela de **templates de ritos** — apenas se usuários pedirem relatórios automáticos por cadência. --- ## 4. Escopo técnico do painel (Main Table) Objetivo da UI: aproximar-se da foto de referência (grupos por **Objective**, linhas de **projetos** com status/custo, aninhamento de **KPIs**), **derivando** a hierarquia do modelo existente: - **Objetivo** → `strategy_objectives` - **Projetos** → união deduplicada de: - `strategy_key_result_links.project_id` onde o KR pertence ao objetivo; - `project_id` implícito via `strategy_key_results.project_kpi_id` → `project_kpis.project_id` - **KPIs / KRs na linha de baixo** → cada KR ligado àquele projeto (por link ou por KPI); opcionalmente listar `project_kpis` estratégicos do projeto quando fizer sentido **Colunas sugeridas (inspiradas na referência, dados permitindo):** - Projeto: nome, link para `project-detail.html` - Status do projeto: `projects.status` (já carregado em `getOKRs`) - Progresso / nota: agregação de progresso dos KRs daquele projeto sob o objetivo (média ponderada ou simples — definir na implementação) - Custos: ver decisão de produto — soma de `project_budget_cost_entries` (actual) por projeto **ou** placeholder “—” quando não houver dado - Timeline / datas: intervalo mín/máx das datas relevantes (projetos ou KRs) se existirem nos dados ligados **Arquivos principais a tocar:** - `[js/strategy-service.js](../js/strategy-service.js)` — enriquecer `getOKRs` (ou método auxiliar) com agregados de custo por `project_id` quando necessário; não quebrar consumidores atuais - `[js/strategy-okr.js](../js/strategy-okr.js)` — novo renderizador de “Main Table” + função `buildObjectiveProjectTree(objectives)` (puramente derivada) - `[strategy-okr.html](../strategy-okr.html)` — nova aba ou seção “Main Table” / “Quadro”, CSS de tabela responsiva - `[js/translation/i18n-strategy.js](../js/translation/i18n-strategy.js)` — strings do painel + bloco colapsável “Cadência recomendada” (texto curto derivado deste plano) **O que não muda no schema na v1 do painel:** nenhuma migração obrigatória se custos forem opcionais ou lidos de tabelas já existentes. --- ## 5. Integração “cadência” na experiência (baixo código) 1. **Bloco de ajuda** no topo da página OKR (colapsável): resumo de 5–8 linhas: anual / trimestral / check-in + link para este documento ou manual do usuário. 2. **Placeholder de “Próximo check-in”** (opcional): texto estático configurável ou vazio — sem backend. 3. **Filtro por `cycle`**: já existe; melhorar labels de exemplo (`FY2026`, `2026-Q1`) na documentação e no placeholder do campo ao criar objetivos (quando CRUD existir). --- ## 6. Fases de entrega sugeridas | Fase | Entrega | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | **Fase A** | Painel Main Table somente leitura: Objective → Projetos → linhas de KR/KPI; colunas status + progresso; custo opcional ou “—”. | | **Fase B** | Agregação de custo por projeto (query única / view opcional) se a Fase A validar a necessidade. | | **Fase C** | Conteúdo de cadência (help + i18n) alinhado às seções 2–3 deste doc; sem obrigatoriedade de novos campos. | | **Fase D (opcional)** | Persistência leve de check-in (`last_reviewed_at` em KR ou tabela `okr_check_ins`) **somente** após uso real. | --- ## 7. Erros comuns (checklist de UX, não validação no banco) Incluir no manual / tooltip curto: - KR como lista de tarefas; demais OKRs; revisar só no fim do trimestre; OKR só como cobrança; meta sem dono; não separar resultado de iniciativa. --- ## 8. Referências no código - Migração OKR: `[supabase/migrations/20260426000000_strategy_okr_sprint5.sql](../supabase/migrations/20260426000000_strategy_okr_sprint5.sql)` - View KRs: `vw_strategy_okr_key_results` - Controller atual: `[js/strategy-okr.js](../js/strategy-okr.js)` - Carga de dados: `StrategyService.getOKRs` / `getOKRContext` em `[js/strategy-service.js](../js/strategy-service.js)` --- ## 9. Resumo executivo - **Painel**: hierarquia visual **derivada** de objetivos, KRs, links e KPIs — sem novo conceito de “projeto sob objetivo” no PostgreSQL. - **Cadência**: o texto que você forneceu vira **north star operacional** no produto (ajuda, filtros por `cycle`, documentação), não um motor inflexível na primeira versão. - **Flexibilidade**: convenções em `cycle`, descrições e ritos humanos; evolução para campos dedicados só se necessário.