- Home
- Skills
- Technical Documentation
- Ubiquitous Language Auditor
Works with the AI Agents you already use
Ubiquitous Language Auditor
Builds a glossary of your domain from the code rather than from prose, and reports where the naming has gone wrong
$5
/moSubscription · cancel anytime
Secure checkout via Stripe
- Always the latest version
- Delivered live to your agent via MCP
- Cancel anytime, access ends at period end
Ubiquitous Language Auditor
Example session with this skill installed
Half this codebase says Customer and half says Client. Build me a glossary from the code and settle it.
- Read your context and instructions
- Compiled the ubiquitous language auditor
Ubiquitous language — orchard — 2026-09-09
Read: all 9 files — orchard/{billing,crm,support,scheduling,notifications}/, both migrations, README.md | Skipped: nothing; no vendored, generated or superseded code is present, and both migrations create live tables.
19 terms (none left off the 40 cap), 2 synonym sets, 2 homonyms, 4 spoken but undeclared.
Headline: three names for one person are joined by nothing but three docstrings and a shared integer — clients.client_id is BIGINT PRIMARY KEY with no foreign key to customers, and no module imports any other.
Glossary
| term | means | declared at | reach |
|---|---|---|---|
| Customer | someone who pays us; the id every other module keys off | orchard/billing/models.py:6, migrations/001_customers.sql:1-2 | 3 endpoints, 1 table, 13 refs; defined-against by crm and support |
| Client | the person we sell to — the same person as Customer | orchard/crm/models.py:5, migrations/002_clients.sql:1-2 | 1 table, 6 refs, local to crm |
| Account | support's word for the same person | orchard/support/models.py:5 | 4 refs, local to support, no table |
| Order (billing) | a purchase — what was bought and what was charged | orchard/billing/models.py:22 | 1 endpoint, 4 refs, no table |
| Invoice | a charge raised against a customer; carries issued_at only — nothing declares the monthly cycle | orchard/billing/models.py:14 | 1 endpoint, 5 refs, no table |
the only field all three person-types carry; UNIQUE in customers, not in clients | migrations/001_customers.sql:3, migrations/002_clients.sql:3 | 7 refs, 4 modules, both tables | |
| Job | a unit of queued work | orchard/scheduling/queue.py:5 | 5 refs, local to scheduling, no table |
| order (scheduling) | position in the run queue, lower runs first | orchard/scheduling/queue.py:8 | 3 refs, local to scheduling |
| account_manager | the staff member who owns a client relationship | migrations/002_clients.sql:4, orchard/crm/models.py:10 | 1 table, 2 refs, local to crm |
| billing_country | the country a customer is billed in | migrations/001_customers.sql:4, orchard/billing/models.py:10 | 1 table, 2 refs |
| lines | declared but undefined — an untyped list on Order and on the POST body; no line-item type exists | orchard/billing/models.py:26, orchard/billing/api.py:18 | 1 endpoint, 2 refs |
| plan | declared but undefined — a bare str on Account, never set, read or enumerated | orchard/support/models.py:9 | 1 ref |
| ... | 7 more glossary rows, cut to fit this listing field |
Excluded as pattern vocabulary, not domain vocabulary: ClientRepository, AccountService, QueueHandler, NotificationService, EmailHandler.
One idea, several names
The person who pays us
Customer — orchard/billing/models.py:6, migrations/001_customers.sql:1 — 13 refs, crosses the HTTP boundary at three paths (/customers/{customer_id}, /invoices, /orders) and the database boundary
Client — orchard/crm/models.py:5, migrations/002_clients.sql:1 — 6 refs, one table, local to crm; no endpoint, no importer
- Account —
orchard/support/models.py:5— 4 refs, local to support; no table, no endpoint
Costs: 3 declarations, 23 code references, 2 tables, 2 primary-key columns and 3 public endpoint paths. The expensive one is the endpoint prefix /customers/ — an external contract that cannot be renamed without a deprecation window. Second is the pair of primary keys: customers.customer_id is BIGSERIAL, clients.client_id is plain BIGINT with no REFERENCES, so the claim at orchard/crm/models.py:6 that client_id IS customer_id is enforced by prose and by nothing else. migrations/002_clients.sql also drops the UNIQUE on email that 001 carries, so the two tables are free to disagree about the same person today. The docstring dates the split to "the 2024 CRM migration" and records that the tables were never merged — this collision is a migration that stopped halfway, not a naming preference.
Evidence points to
Customer. It is the oldest at the boundary (migration 001 precedes 002), it is the only one of the three the outside world sees, it generates the ids the other two borrow (BIGSERIAL against BIGINT), and both rivals define themselves by pointing at it — client_id IS customer_id, account_id is the billing customer_id — while it points at nobody. Settling it costs crm and support a rename each and leaves the public API untouched; settling it the other way costs an API version.
One caveat belongs with that winner: the README's word is neither of the three (see Spoken but not declared), and if
subscriber turns out to be the business's real word, this decision reopens with a fourth candidate.
The money total on a billing document
- amount_cents —
orchard/billing/models.py:17— 1 ref, on Invoice - total_cents —
orchard/billing/models.py:27— 1 ref, on Order
Costs: nearly nothing — two fields, one file, no table and no endpoint exposes either. Worth listing only because both are new-ish and the next billing document declared will pick a third name.
Evidence points to: nothing decisive — both are one line old and neither has crossed a boundary. Cheapest to settle now by fiat, whichever a person prefers.
One name, several ideas
Order
- means
a purchase — what was bought and what was charged — at orchard/billing/models.py:22, exposed as POST /customers/{customer_id}/orders at orchard/billing/api.py:17
- means a sequence position in the run queue, lower first, at
orchard/scheduling/queue.py:8
Costs: the quiet kind. place_order and sort_by_order both read correctly and mean unrelated things, so a grep for order to audit purchases returns the queue field, and any search-and-replace across both modules is wrong in one of them. The cost is deferred rather than absent: nothing imports across modules today, so the two never meet in one file — the day scheduling gains a job triggered by billing, they do, and a list[Order] parameter will be ambiguous at the signature. A maintainer is already paying interest on this by hand, in the comment at orchard/scheduling/queue.py:12 that exists only to say the two are unrelated.
Needs: a second word for the
scheduling one — position, sequence or rank. That side is one int on one dataclass used by one function, entirely inside one module, against billing's Order sitting on a public endpoint; and "order" as a purchase is the business's word, while "order" as a position is generic English that any of three synonyms replaces without loss.
Account
- means the person who pays us at
orchard/support/models.py:5 - means
the sales relationship — the book of business a staff member owns — inside account_manager at migrations/002_clients.sql:4 and orchard/crm/models.py:10
Costs: small and mostly to readers. A grep for account returns a customer record in support and a staff name field in crm, and a developer in crm meeting account_manager reasonably expects an Account nearby — there is none, because crm calls that same person Client. It is a compound rather than a competing declaration, which is why it ranks below Order.
Needs: nothing of its own yet — settle it second. If Account loses the synonym decision above, support's Account becomes Customer and this collision dissolves without a separate conversation. Only if Account somehow wins does the CRM field need a word of its own (relationship_owner, sales_owner).
Spoken but not declared
subscriber — heard in README.md:5 and README.md:6, in bold, as the platform's headline noun — no class, table, column or endpoint anywhere. Missing concept or retired word is exactly the question, and it changes the synonym decision above: nothing in the code declares a subscription — no term, renewal, period or recurrence — so either the README describes a business the code has not caught up with, or "subscriber" is prose for the thing already called Customer. A person answers this, not the repo.
churn / the 30-day read window — heard in README.md:6 ("Churned subscribers keep read access for 30 days") — no status, state, flag, timestamp or duration is declared in any module or either table. Either an unimplemented rule or a behaviour enforced somewhere outside this repo; which one decides whether it is a bug or a boundary.
ticket — heard in README.md:5 and in the method name open_ticket at orchard/support/models.py:13, which takes a subject and returns a bare int — no Ticket type, no tickets table, nowhere for the subject to be stored. Support can open one and the codebase cannot describe one. Missing concept.
the monthly invoice — heard in README.md:5 ("gets an invoice each month") — Invoice declares issued_at and nothing else; no period, cycle, due date or schedule is declared, and the scheduling module knows only about generic Jobs.
Not audited
- Every method and function body in the repo is a
...stub, so each meaning above rests on a declaration, a docstring or a column type — no behaviour was available to confirm any of it, and the three docstrings asserting a shared id space are the load-bearing evidence for the synonym set. - No tests, fixtures or seed data exist to cross-check the names against runtime.
Invoice,Order,Joband the undeclared Ticket have no schema in this repo; onlycustomersandclientsare created. Whether those tables live in another repo or do not exist yet was not determinable here, and it bounds how confident the reach counts are for billing's nouns.- Renaming was not performed and is not proposed as an action: the winner and its price are recorded above for a person to decide.
Say the word and this gets saved to the repo as GLOSSARY.md.
Subscription · always the latest version
- Secure checkout via Stripe
- Cancel anytime
- Delivered live via MCP
About this skill
Three people wrote three modules and the same thing ended up with three names. This skill reads the codebase and reports the vocabulary it actually speaks: a glossary where every term is anchored to the declaration that defines it, the cases where one idea wears several names kept apart from the cases where one name covers several ideas, and the words your team says that the code has never heard of. Each collision is priced by what it crosses, not by how often it appears.
What it does
Builds a glossary of your domain from the code rather than from prose, and reports where the naming has gone wrong. Terms come from declarations - types, tables, endpoints, queues, enum members - each with its path and line. Collisions are split into two lists that are never merged: one idea under several names, and one name covering several ideas. They are ranked by what they cross, because a term at a module boundary costs more to settle than one used forty times inside a single file.
Try it first
Open a repo with more than one module in it and say "build a glossary of our domain from the code". You should get back a header with the counts and what was skipped, a glossary table ordered by reach, the synonym sets and the homonyms as separate sections with a cost line on each, and a list of the terms people say that have no declaration behind them.
What it needs
An agent that can read and search the repo - Read, Grep, Glob and Bash. No API keys, no MCP servers, no network access. Language-agnostic, because it reads declarations rather than parsing a grammar.
It does not rename anything, and that is deliberate - choosing the winning name is a conversation and carrying it through a codebase is a refactor, so this hands both of them evidence and stops. It cannot tell a retired word from a missing concept: when your team says something the code never declares, it says so and asks rather than guessing which. Its judgement about what counts as domain vocabulary is a judgement - it excludes pattern words like Handler and Repository unless your business genuinely uses them, and on a codebase whose domain really is software it will exclude too much. And it is only as good as the declarations: a codebase that keeps its meaning in string keys and dictionaries rather than in named types gives it very little to anchor to, which it will say plainly instead of padding the glossary.
How to use
- 1
Connect your agent to the Agensi MCP
Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup
- 2
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 3
Ask for what you need
Your agent loads this skill and uses it on your task. It always asks before any payment.
Reviews
No reviews yet
Be one of the first to try it. Every listed skill goes through the trust checks below.
Security scanned
Checked by our 8-point scan before listing
Fresh listing
Recently published to Agensi
Free forever
No account required to browse
Trust & safety
Security scan
Security scan passed 1 month ago