Skip to content
Meta-Rational Software Development with Engineering Skills for AI

One word, many meanings across departments

Aspects: ontology · categories (reflection on boundaries) · epistemology (relating formal and informal) · breadth of considerations

Signals you are in this situation

Section titled “Signals you are in this situation”
  • Reports from two systems disagree on a basic count such as customers or orders.
  • Meetings stall on definitions instead of decisions.
  • The code has near-synonyms for one thing: client, account, customer, party.
  • Integrations between departments need translation tables.
  • New hires ask what a term means and get different answers.

The situation

Section titled “The situation”

A company that has grown by acquisition sets out to integrate its systems. Marketing, sales, and finance all keep records of customers. To marketing a customer is a qualified prospect; to sales, the person with authority to sign; to finance, whoever is responsible for paying the bill. Each department’s database encodes its own meaning, the databases do not talk to each other, and when management asks how many customers the company has, there is no single answer. The article by David Hay and colleagues that describes this case proposes treating prospect, signer, and payer not as kinds of thing but as roles played by people and organisations, so that one shared model can serve all three departments.

William Kent gives the older, smaller version of the same problem. An inventory system uses “part” to mean a kind of part, of which there are many in stock; a quality-control system uses “part” to mean one physical object with its own test results. Each system works because its users resolve the word from context without noticing. Integrate the two files and that silent resolution is gone.

The meta-rational perspective

Section titled “The meta-rational perspective”

Words in a working group are reasonable, not rational: their meaning is settled by context, purpose, and habit, and that is enough for people who share the context. Software cannot do this. A program has one ontology, fixed and usually implicit, and Chapman’s point about fixed ontologies applies exactly here: they work while they are good enough, and when they are not, rationality has no way to repair them because it cannot see them. Choosing which meaning of “customer” the system will carry is therefore not a technical detail to be settled by whoever writes the schema. It is an ontological decision about what the company is going to count as a customer, and it has to be made explicitly, by people from each context, with the reasons recorded.

Eric Evans’s book on domain-driven design made the central insight mainstream: get the domain ontology right and organise the system around it. Chapman regards that insight as correct and important, and the methodology that grew up around the book as largely a distraction from it. Daniel Jackson adds a second layer: users also bring an ontology of software itself, formed by every similar program they have used, and a system that departs from it will be misunderstood constantly. Both books are about the same meta-rational move, relating the formal categories a program must have to the informal ones people already use.

The failure is not that departments disagree. It is that the disagreement was never surfaced, so the system took a side without anyone knowing there were sides.

Failure path

Section titled “Failure path”
1 Three departments three meanings of “customer” 2 Pick one meaning the requester's, unnoticed 3 Write a glossary skipped: “everyone knows what it means” 4 Merge the databases one customer table 5 Build the reports counts, funnels, invoices 6 “How many customers?” three answers 7 Blame the data a cleanup project is opened reconcile by hand, merge again, repeat
How the situation goes wrong when handled purely rationallyHow to read

One meaning of the word is chosen, usually the requester’s, and no glossary is written because everyone assumes they already agree. The databases are merged into one customer table and reports are built on it. The first executive question exposes three incompatible answers, and the discrepancy is diagnosed as a data-quality problem, which launches a cleanup project that reconciles the records by hand and leaves the cause untouched.

Corrected path

Section titled “Corrected path”
1 Collect each usage one questionnaire per department to-questionnaire: Turns a question you cannot answer into a questionnaire for the person who can.to-questionnaire 2 Challenge the term prospect, signer, payer: roles domain-modeling: Challenges overloaded terms and writes the glossary and decision records.domain-modeling 3 Write the glossary the decision, and why CONTEXT.md: The project glossary: the domain vocabulary every skill reads and writes.CONTEXT.md ADRs: Architecture decision records: dated, reasoned decisions kept in docs/adr/.ADRs 4 Draw the seams one context per role, not per team codebase-design: Vocabulary for deep modules and where seams belong.codebase-design 5 Build to the glossary tests named in its terms tdd: The red-green-refactor loop with rules for tests worth keeping.tdd implement: Implements a spec or tickets test-first at agreed seams.implement 6 Check the language re-pitch in the shared terms wait-what: Stops the agent and asks it to re-pitch in plain language using the project's terms.wait-what 7 Revisit on change a new department, an acquisition grill-with-docs: Grilling that also writes glossary entries and ADRs as decisions settle.grill-with-docs a new usage arrived: challenge the term again a term drifted: fix the glossary first
The same path with skills inserted at the break pointsHow to read

The same steps run in the same order, but the word is treated as a question before it becomes a column. Each department’s usage is collected on its own terms, the term is challenged until roles emerge from behind the nouns, and the resulting glossary is a recorded decision that the code, the tests, and the conversations are all held to. Seams in the codebase follow the roles rather than the org chart. The loops catch drift early: a term that has slipped goes back to the glossary, and a new department or acquisition reopens the challenge rather than being bolted onto the old meaning.

Skills for this situation

Section titled “Skills for this situation”
Skill When to invoke it here What it changes Example
to-questionnaire First, once for each department that uses the word. Collects each group’s meaning from the people who hold it, in their own terms, rather than having one analyst guess for all three. /to-questionnaire for the finance controller: when is someone a customer to you, and what do you need to know about them?
domain-modeling With the questionnaires in hand. Challenges the overloaded term with concrete scenarios: is a prospect who never signs a customer? Is a parent company that pays for a subsidiary? Splits the noun into roles and records them. /domain-modeling customer: prospect, signer, payer, and who can be more than one
grill-with-docs When the split has consequences someone will dispute. Runs the interview and writes the ADR at the same time, so the decision about what the company counts as a customer carries its reasoning. /grill-with-docs the decision to model customers as roles rather than records
codebase-design Before the merged schema is built. Places seams where the contexts differ, so each role’s data has a home and the shared parts are shared on purpose. Deep modules per role instead of one wide table. /codebase-design a seam between the prospect pipeline and the billing model
tdd and implement For the build. Test names and interfaces use the glossary’s terms, which keeps the code honest about which meaning it is handling. /implement the shared party model from the ADR
wait-what Whenever a conversation about the system starts to drift. Makes the agent re-pitch its last message in the glossary’s vocabulary, which exposes a term that has quietly changed meaning. /wait-what
grill-with-docs, again When a new department, product line, or acquisition arrives. Reopens the term instead of mapping the newcomer’s usage onto the existing one. The glossary is revised, not defended. /grill-with-docs how the acquired company's account concept maps onto our roles

Sources

Section titled “Sources”