F10. Single Point of Knowledge

Diagnoses: D10. Scattered Knowledge Related fixes:

• F4 (Parse, Don’t Validate) — a parser is the single point of knowledge for a data shape
• F6 (Deep Modules) — information hiding presupposes the knowledge has first been consolidated somewhere
• F11 (Lifted Invariants) — F10’s data-shape sibling: F10 is about a rule defined once vs. followed by repetition; F11 is about a constraint on data established once vs. re-checked at many call sites

The concept

When knowledge — a convention, policy, structural assumption, domain rule — exists only as a pattern repeated across files, nobody can confidently understand, change, or verify it. There might be an exception somewhere. There might be an inconsistency introduced last month that nobody noticed.

A single authoritative definition fixes this. One place to read, one place to change, one place to test. Consumers depend on the definition through its interface instead of reimplementing the knowledge themselves.

This is related to information hiding (Parnas, F6), but precedes it. Information hiding conceals design decisions behind interfaces. Single Point of Knowledge is more fundamental: making implicit knowledge explicit and giving it a home. Before you can hide a decision behind an interface, you must first recognize that a decision exists and consolidate it. Most scattered knowledge isn’t recognized as a “design decision” — it’s just “how things are done here,” encoded through repetition.

OO encapsulation, DRY, configuration-as-code, schema definitions, type-driven design — all different mechanisms for the same goal: one piece of knowledge, one place in the code.

The confidence problem

The main cost of scattered knowledge is loss of confidence. When a convention is followed in twenty places but defined in zero, a reader can never be certain they have the full picture. The lurking question: what if there’s an exception I haven’t seen?

This compounds. Developers reluctant to change what they can’t fully map. Coding agents that can’t find an authoritative definition hedge, add defensive checks, or silently propagate inconsistencies. The system resists change because nobody knows the blast radius.

One authoritative definition restores confidence. The developer changes it in one place; the compiler (or tests, or the single call site) shows what else must adapt.

Remedy

• Name the knowledge. When a convention is followed across multiple places, ask: is it defined anywhere? If not, it needs a home.
• Give it a single definition:
  • Structural convention → schema or builder function
  • Naming rule → generator function
  • Policy → policy function consulted, not reimplemented
  • Configuration assumption → constant or config object
  • Domain constraint → type whose construction enforces it (see F4-parse-dont-validate.md)
• Make consumers depend on the definition. If you define a directory layout schema but every module still hardcodes its own paths, you’ve created documentation, not consolidation.
• Test the definition, not each instance. One definition means one focused test. Scattered knowledge requires a test per instance — and you’ll miss the ones you don’t know about.