nubos-pilot

Appearance

ADR-0012: Completeness Mandate as Pflicht-Boilerplate ​

Context and Problem Statement ​

Nubos AI agents operate under user instruction "The marginal cost of completeness is near zero with AI. Do the whole thing." That instruction had no canonical home: it lived in conversation, was paraphrased per agent, and drifted across spawns. Two failure modes followed:

  1. Doctrine drift: each agent's prompt re-stated the rules in its own words, weakening them ("Do tests" became "consider tests" became "tests where reasonable").
  2. Mechanical un-enforceability: an LLM agent can ignore documentation. The doctrine had no mechanically checkable shape.

We need a single source of truth that every agent and every workflow references verbatim, and a linter that fails the build when the reference is missing.

The Rule ​

The Completeness Mandate is a single 12-rule document at templates/COMPLETENESS.md. Every agents/np-*.md MUST contain a ## Completeness Mandate heading and link to that file. Every workflows/*.md MUST contain a ## Definition of Done heading and link to that file. The linter bin/check-completeness.cjs enforces both invariants and runs as part of npm test.

The 12 rules are:

  1. Do the whole thing.
  2. Do it right.
  3. Do it with tests.
  4. Do it with documentation.
  5. Aim to genuinely impress, not politely satisfy.
  6. Never offer to "table this for later".
  7. Never leave a dangling thread.
  8. Never present a workaround when the real fix exists.
  9. Search before building.
  10. Test before shipping.
  11. Ship the complete thing.
  12. Boil the ocean.

Each rule has a "Mechanical check" line in templates/COMPLETENESS.md that names the agent or workflow that enforces it (e.g. Rule 3 → executor's verify command; Rule 8 → plan-checker's "workaround" detector; Rule 9 → tool-use audit in Nubosloop).

Decision Drivers ​

  • Single source of truth: one file. Every agent and workflow references it. Updates land in one place; no copy-paste drift.
  • Mechanical enforcement: the linter fails the build when the reference is missing. The doctrine is now CI-grade, not advisory.
  • Audit-friendly: git log -p templates/COMPLETENESS.md is the doctrine's full history. Updates require an ADR; ad-hoc rewrites are forbidden by the ADR process.

Considered Options ​

  • Doctrine as text in CLAUDE.md only: Rejected. CLAUDE.md is a per-runtime managed-block; not all hosts honour it; agents can still ignore it.
  • Doctrine inlined per agent: Rejected. The drift mode this ADR exists to prevent.
  • Doctrine as a single canonical file + agent/workflow link block + linter: chosen.

Decision Outcome ​

Chosen: templates/COMPLETENESS.md as canonical, with linter-enforced reference blocks in every agent and workflow, because it makes the doctrine simultaneously authoritative, audit-friendly, and CI-grade.

File Layout ​

  • templates/COMPLETENESS.md: canonical doctrine (English original + German translation + 12 numbered rules + per-rule mechanical-check pointer + linter contract + provenance).
  • templates/RULES.md: project-wide RULES.md template, references COMPLETENESS.md as foundation in its precedence section.
  • agents/np-*.md: each carries a ## Completeness Mandate block listing the rules that bind that role and linking to templates/COMPLETENESS.md.
  • workflows/*.md: each carries a ## Definition of Done block listing the rules that gate the workflow's exit and linking to templates/COMPLETENESS.md.

Linter Contract ​

bin/check-completeness.cjs exposes:

  • checkAgents(rootDir): every agents/*.md must contain ## Completeness Mandate and link to COMPLETENESS.md.
  • checkWorkflows(rootDir): every workflows/*.md must contain ## Definition of Done and link to COMPLETENESS.md.
  • checkCompletenessFile(rootDir): the doctrine itself must contain exactly twelve sequentially numbered rule headings ### 1. … through ### 12. ….
  • checkAll(rootDir): runs all three.

Tests live in bin/check-completeness.test.cjs. CC-9 validates the live tree on every npm test run.

Consequences ​

  • Good, because the doctrine has one home and one enforcement mechanism.
  • Good, because adding a new agent or workflow without the boilerplate fails CI immediately.
  • Good, because doctrine updates are ADR-bound, with no silent rewrites.
  • Bad, because every new agent has slightly more boilerplate. Accepted; the boilerplate is what makes the doctrine durable.
  • Neutral, because the doctrine is opinionated. That is the point.

More Information ​