Stack Principles

Princípios são guidelines 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 é advisory (sinaliza tensão, não bloqueia).

How to use this document

When facing an architectural decision:

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

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

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

   command? code?).

3. If two principles conflict, find the pair under one of their

   conflicts_with blocks and apply the resolution heuristic.

4. If conflict is not in the matrix, the principle higher in this

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

5. policies/decision-graph.kmd describes the meta-method 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.*

Statement. Resolução instância-por-instâ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.

Rationale. 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.

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

Expressions (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

Conflicts with:

• principle: Don't over-abstract / YAGNI

  resolution: 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ância-by-instância é ok — premature abstraction também é problema. Heurística: regra 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.*

Statement. Em qualquer decisão técnica — framework, SDK, spec, RFC, policy, ou implementação tática/produto — 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. O único atalho permitido é quando o usuário pede velocidade/economia explicitamente. Este princípio é absoluto — não mais escopado só a framework (ratificado pelo owner 2026-05-29).

Rationale. Stack ainda em fase pré-homologação — não há cobrança real de prazo. Retrabalho arquitetural dói em qualquer camada (framework toca dezenas de módulos; produto acumula dívida que trava evolução). Sem deadline real, não há justificativa pra escolher a forma pior de propósito.

Applies to. Toda decisão técnica — framework · SDK · spec · RFC · policy · arquitetura cross-stack · implementação tática · produto · escolha entre opções/abordagens.

Checklist concreta. As dimensões pelas quais se mede "melhor de longo prazo" estão normatizadas em policies/architecture-quality.kmd (12 dimensões; escala é só uma delas, e a D12 — causa-raiz > sintoma é a que operacionaliza este princípio no ranqueamento: esforçotempogating não rebaixa um fix de raiz). Aplicar essa rubrica no desempate.

Expressions:

• 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
• Desempate de opções no /k-go (Regra 13): entre alternativas conformes à Stack, prefere a de melhor arquitetura de longo prazo

Conflicts with:

• principle: Phase Acceleration

  resolution: Quality > Speed em seleção de escopo de design. Phase Acceleration aplica em runtime 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).

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

  desproporcional") resolution: Quality ganha sempre — em qualquer decisão técnica, inclusive tática/produto, prefere-se a solução de longo prazo mesmo a maior custo de esforço. O caveat do hyperscale-first ("ship simples + ticket de promoção") só se ativa quando o usuário pede velocidade/economia explicitamente ("rápido", "MVP", "só pra destravar") — e mesmo aí abre-se ticket nomeando o caminho de longo prazo. Ratificado pelo owner 2026-05-29 (#2 absoluto, não mais escopado a framework/end-of-cycle). YAGNI continua valendo — ver conflito abaixo: longo prazo significa "completo pros usos reais conhecidos", não over-engineer especulativo.

• principle: YAGNI

  resolution: 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 analítico*em LLM (markdown).*

Statement. 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.

Rationale. 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).

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

Expressions:

• 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

Decision tree:

Conflicts with:

• principle: Divide and Conquer (regra dos 3)

  resolution: 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: 3+ instâncias deterministic → binário. Menos de 3, ou analítico → markdown.

• principle: Velocidade de iteração

  resolution: Markdown é mais rápido pra prototipar; binário é mais rápido pra repetir. Heurística: prototipa 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.*

Statement. 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.

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

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

Checklist (5 perguntas) antes de criar item novo:

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