Policy — Stack Principles

Princípios são *uidelines com julgamento* não regras deterministic. Conflitos entre princípios são resolvidos pelas heurísticas embutidas em cada par conflicts_with → resolution. Audit deste arquivo é *dvisory*(sinaliza tensão, não bloqueia).

How to use this document

When facing an architectural decision:

1. *tart with Principle #1 (Meta First)*— ask "is this an instance of a

   pattern I should solve once, or a one-off?"

2. *heck applicable principles*for the decision domain (framework? spec?

   command? code?).

3. *f two principles conflict* find the pair under one of their

   conflicts_with blocks and apply the resolution heuristic.

4. *f conflict is not in the matrix* the principle higher in this

   ranking (lower number) wins by default — *ut document the new conflict in the next edit of this file*

5. *policies/decisiongraph.kmd`*describes the metamethod for reducing

   N decisions to ~3 master decisions; this file lists the principles that feed those decisions.

---

1. Meta First

*Antes de resolver N instâncias, encontre o pattern. Antes de responder N decisões, mapeie o grafo. Antes de criar N artefatos, formalize a forma comum.*

*tatement.*Resolução instânciaporinstância multiplica trabalho, cria drift, e força revisão a cada nova ocorrência. Pattern engine + lens consolidado paga dividendo cumulativo: cada nova instância já cai no caminho pronto.

*ationale.*Engineering leverage é Meta First — Archimedes' fulcrum. Stack tem custo crescente quando cada feature reinventa: Settings tile do voice ≠ do update ≠ do error reporter. O custo do drift cresce com N.

*pplies to.*Framework design · decision making · spec creation · command creation · policy formalization · refactor.

*xpressions*(instâncias deste princípio nesta Stack):

• Code First — encode pattern em binário em vez de N markdowns
• Divide and Conquer — listar reusos antes de criar
• Quality > Speed — escolher solução de longo prazo (pattern resolve uma vez)
• Decision graph — 3 Q-mestre cascateiam 12+ decisões
• Spec audit framework — engine dinâmica vs N audit scripts hardcoded
• /k-audit unificado — 1 comando + subcomandos vs família de N comandos

*onflicts with:*

• *rinciple:*Don't over-abstract / YAGNI

  *esolution:*Meta First aplica quando há ≥3 instâncias do mesmo padrão OU quando o pattern ressurge frequentemente em planning sessions. Caso contrário, instânciabyinstância é ok — premature abstraction também é problema. Heurística: *egra dos 3*(extrair quando a 3ª instância aparece, não antes).

---

2. Quality > Speed

*Sempre optar pela solução mais completa, mais escalável, mais indicada pensando no longo prazo. Tempo não é restrição.*

*tatement.*Em design de framework, SDK, spec ou RFC, escolher a forma estruturalmente correta mesmo que demore mais. Não shippar "v1 com limitações pra arrumar depois" se uma forma melhor é alcançável.

*ationale.*Stack ainda em fase pré-homologação — não há cobrança real de prazo. Trabalho de framework é onde retrabalho dói mais (toca dezenas de módulos depois). Erro arquitetural em framework custa muito mais que em produto.

*pplies to.*Framework · SDK · spec design · RFC · policy creation · arquitetura cross-stack.

*xpressions:*

• Generaliza feedback_kdb_id_v2_methodology (originalmente escopado a

  kdb+id v2) para toda decisão Stack-wide

• Justifica preferir koder-spec-audit engine dinâmica em vez de hardcoded
• Justifica refactor do /k-commit em fases mecânicas → binário
• Justifica criar SDK widget + spec antes de adoção sweep

*onflicts with:*

• *rinciple:*Phase Acceleration

  *esolution:*Quality > Speed em *eleção de escopo de design* Phase Acceleration aplica em *untime de execução*(/k-go modo D não pede confirmação a cada step). Não há conflito real: são camadas ortogonais (decisão estratégica × execução tática).

• *rinciple:*Hyperscale-first caveat ("ship simples se esforço

  desproporcional") *esolution:*Em design *ross-stack* Quality ganha — refactor custoso vale o investimento. Em *eadline real de produto* Hyperscalefirst ganha (ship simples + ticket followup pra promoção futura). Heurística: *e o trabalho é da Stack/framework, Quality; se é de produto endofcycle, Hyperscale-first caveat.*

• *rinciple:*YAGNI

  *esolution:*Quality > Speed não autoriza over-engineer especulativo. Significa "completa pra os usos reais conhecidos", não "completa pra futuros hipotéticos". Heurística: a feature precisa atender ≥3 consumers identificados, não imaginados.

---

3. Code First

Encode o *determinístico*em código (binário); deixe o *nalítico*em LLM (markdown).*

*tatement.*Operações com input fixo → output fixo devem ser binários. LLMs interpretam markdown de forma sutilmente diferente entre Claude, Codex, Gemini, etc. Binário garante resultado idêntico cross-LLM.

*ationale.*Stack hoje tem ~10% binário e ~90% markdown — a inversão é necessária. Cada operação determinística escondida em markdown é dívida de drift (cada IA implementa um pouco diferente).

*pplies to.*Comandos /k-* · audit scripts · sync utilities · parsers · validators · generators.

*xpressions:*

• koder-test-gate (existente) — enforcement de regression test
• koder-stackdoc (existente) — sync de doc do Stack
• kicon (existente) — geração de variantes de ícone
• koder-spec-audit (proposto) — engine de spec audit
• koder-commit (proposto) — fases mecânicas do /k-commit
• koder-manifest (proposto) — parsing de UI → JSON
• koder-parity-scan (proposto) — Fase 2 do /k-parity

*ecision tree:*

*onflicts with:*

• *rinciple:*Divide and Conquer (regra dos 3)

  *esolution:*Não há conflito — eles compõem. Code First diz "se existe pattern determinístico, encode em código"; DnC diz "extrair pattern só após 3 instâncias". Juntos: *+ instâncias deterministic → binário* Menos de 3, ou analítico → markdown.

• *rinciple:*Velocidade de iteração

  *esolution:*Markdown é mais rápido pra prototipar; binário é mais rápido pra repetir. Heurística: *rototipa em markdown; quando estabiliza (3+ usos sem mudança), promove a binário.*

---

4. Divide and Conquer

*Antes de criar comandospecpolicy/binário novo, listar o que já existe que pode ser reusado.*

*tatement.*Stack tem drift de lógica duplicada — /k-commit e /k-housekeep ambos sincronizam doc; /k-commit e /k-go ambos varrem backlog; /k-parity Fase 2 e /k-test-gen-* ambos parseiam UIs. Cada drift é dívida.

*ationale.*Reuso explícito é mais barato que detectar duplicação depois (/k-audit dnc pega só sintomas, não a causa).

*pplies to.*Criação de comando · spec · policy · binário · widget · endpoint API.

*hecklist (5 perguntas) antes de criar item novo:*

1. Existe binário Koder com função similar?
2. Existe `tasks