Policy — Code First

Encode the *eterministic*in code; leave the *nalytical*to LLM. The default has been markdown; this policy inverts it where appropriate.

When this applies

Always — every time a command, audit, validator, sync, parser, or generator is being created or extended.

Why

Three LLMs (Claude, Codex, Gemini) interpreting the same markdown command will produce *utilmente diferente*results. For mechanical operations this is a bug — not a feature. Binary tools eliminate the variance.

Concrete examples of past divergence in this Stack:

• /k-commit step "version bump" interpreted differently per LLM (some

  bumped patch, some bumped minor for the same change)

• /k-parity Phase 2 "feature scan" produced different feature lists

  depending on which heuristic the LLM picked

• /k-test-gen-* (21 commands) generated subtly different test scaffolds

Token economy (secondary motivation)

Beyond determinism, every operation that lives in a binary is an operation the LLM no longer pays for. A markdown phase that an agent rereads, reinterprets and re-executes on every invocation costs tokens *er session* Promoting that phase to a binary collapses the recurring cost to a one-time cost (writing the binary) plus a constant (invoking it). For pipelines run dozens of times per week — /k-commit, /k-housekeep, /k-test, /k-audit — the savings compound across sessions and across LLMs.

This is a *econdary*motivation: determinism is the primary reason to promote, token economy is the multiplier that makes the case obvious in borderline situations (an algorithm that is almost deterministic with one analytical step still wins by extracting the deterministic core to a binary). When sizing a candidate, weigh both — drift cost plus persession token cost — against the onetime cost of writing the binary.

Decision tree

Apply when scoping a new command or expanding an existing one:

*ule of thumb:*if you can write the algorithm in pseudocode without "and then the LLM decides", it's deterministic — make it a binary.

Inventory — current binaries (Stack today)

These already follow Code First:

Inventory — candidates to migrate

These are markdown commands with deterministic logic that should become binaries (proposed in ticket KSTACK-101):

Anti-patterns

*on't:*

1. *efault to markdown*— the default has historically been markdown.

   The decision now should be: "is there a reason this can't be a binary?" If no reason, make it a binary.

2. *ncode "if the LLM thinks it should…"*— that's analytical.

   Either write a deterministic rule or accept LLM variance.

3. *ury determinism inside markdown narrative*— if the spec includes

   "for each X, do Y if Z", that's pseudocode → it's a binary.

*o:*

1. *rototype in markdown*when shape is unclear. Markdown is fast to

   iterate; binary is fast to repeat.

2. *romote to binary when stable*— 3+ uses without changes ≈ ready.
3. *LM orchestrates binaries*— the LLM-facing surface stays

   declarative ("call koder-X with these args"), but the work is binary.

Conflicts

See policies/stack-principles.kmd §3 for resolution heuristics with:

• *ivide and Conquer*(no conflict — they compose: 3+ deterministic uses → binary)
• *elocidade de prototipagem*(prototype markdown; promote when stable)

Audit

/k-audit code-first (futuro, parte do ticket KSTACK-101) executa esta policy em modo advisory:

1. Walks `metacontextcommands