Domain Modeling and Project Glossaries

What it does

This skill actively changes the domain model rather than merely reading an existing glossary. It challenges language that conflicts with GLOSSARY.md, checks business claims against code and probes relationships with edge cases. Resolved terms are recorded immediately without code details. The source supports multiple contexts through GLOSSARY-MAP.md and creates files only when there is something useful to record. Architecture decision records are offered sparingly for consequential, surprising trade-offs.

When to use it

• Customer, user and account are used interchangeably across a product.
• Partial cancellation exposes an unclear relationship between orders and order lines.
• Several domains use the same term with different meanings.

Step-by-step workflow

1. Read the current glossary or context map and the relevant decision records.
2. Identify overloaded terms and ask which business concept each one represents.
3. Test the proposed definitions with a concrete edge-case scenario.
4. Compare the agreed behavior with source code and resolve contradictions explicitly.
5. Record stable definitions immediately; offer an ADR only for a meaningful durable trade-off.

Example request

Use domain-modeling while we define refunds. Our team currently uses refund, cancellation and credit as synonyms. Check the glossary and code, then test partial shipment, a cancelled unpaid order and a store-credit refund. Propose canonical terms that separate those cases. Keep implementation details out of GLOSSARY.md. Record an architecture decision only if we resolve a hard-to-reverse trade-off that would otherwise surprise a future maintainer.

Worked example

An unpaid cancelled order may require no transfer of money, while a refund follows an earlier payment. Treating both as refunds can confuse reporting and user messages. The session should make that distinction explicit, identify where existing code uses a different meaning and record only the agreed business definitions. A database table name does not belong in the glossary. If two bounded contexts legitimately define credit differently, the context map can preserve both meanings instead of forcing false consistency.

What you get

A sharpened glossary and, when justified and agreed, a focused architecture decision record with the trade-off context.

How to evaluate the result

• Ensure every definition uses domain language rather than file paths or schema details.
• Test whether the agreed terms distinguish the troublesome scenarios.
• Check context ownership and record only decisions actually resolved.

What you need

A domain expert who can resolve business decisions, existing terminology and relevant code or examples. Companion glossary and ADR formats should remain available.

Setup and activation

The publisher documents plugin setup for Claude Code, Codex and Copilot, and manual Agent Skills setup for Gemini CLI and other clients. Choose one distribution method per client to avoid duplicate skills. The engineering collection expects project-specific tracker, triage-label and document-location settings from setup-matt-pocock-skills. Keep referenced companion skills and files available. This catalogue review does not install or run them; scan the exact source before any later installation. Client tools, permissions and subagent support still need separate validation.

Limits and considerations

The agent cannot establish business policy from code alone. Contradictions need an explicit decision. A glossary is neither an implementation specification nor a session scratchpad. Recording every minor preference as an ADR creates noise.

Related workflows

• Use grill-with-docs when requirements discovery and terminology need to happen together.
• Use to-spec to turn agreed behavior into an implementation-ready requirement record.

License and reuse

MIT at repository level (Copyright 2026 Matt Pocock). Preserve the copyright and permission notice when redistributing substantial source material; inspect any separately licensed dependencies or assets.

Further reading

• Publisher README: client setup and companion skills
• Reviewed SKILL.md (immutable commit)
• Reviewed MIT license