agentleFS
Sign inStart free
imMamdouhaboammarimMamdouhaboammar/matts-skills-into-chatgpt/skills/domain-modeling/SKILL.md

domain-modeling

Skill8 starsChanged 2 months agoMITView on GitHub

Build and sharpen a project's domain model, ubiquitous language, and architectural decision records. Use when establishing codebase terminology, challenging fuzzy concepts, writing ADRs, or updating CONTEXT.md — even if the user says \"define our terms\". Do NOT use for general code refactoring without domain shifts.

We split this skill into the rules it gives an agent

5 rules. 0 are common, 4 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 183 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Selective ADR Threshold: Only author an ADR when a decision meets all 3 criteria: (1) Hard to reverse, (2) Surprising without context, (3) …

    line 17
  2. Very specific:

    Action: Check if a root CONTEXT-MAP.md exists (multi-context) or single CONTEXT.md / docs/adr/.

    line 45
  3. Distinctive:

    Key Point: Create glossary files lazily on the first resolved term.

    line 46
  4. Distinctive:

    Action: Search the codebase for entity names and check whether existing schemas agree with the user's description.

    line 55
  5. Distinctive:

    Key Point: Document Context, Decision, Status, and Consequences.

    line 64

“Common” is measured: kept by at least 6 in 10 of the 183 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Domain Modeling

Actively establish, sharpen, and enforce ubiquitous domain language (CONTEXT.md) and architectural decision records (docs/adr/*.md) to prevent semantic drift across agents and engineering teams.

Core Invariants

  1. Active Semantic Enforcement: Proactively challenge overloaded, ambiguous, or colloquial terms and align them with canonical definitions in real time.
  2. Immediate Inline Glossary Updates: Capture domain terms into CONTEXT.md the instant they crystallize; never batch glossary edits to the end of a session.
  3. Strict Implementation-Free Glossary: CONTEXT.md must contain zero implementation details, frameworks, or database choices—it is a pure domain dictionary.
  4. Selective ADR Threshold: Only author an ADR when a decision meets all 3 criteria: (1) Hard to reverse, (2) Surprising without context, (3) The result of a real trade-off.
  5. Codebase-Glossary Alignment: Cross-reference terminology with live codebase entities and flag discrepancies immediately.

Architecture & Map of Content (MOC)

[ Domain Discussions / User Prompts ] ──► [ Semantic Challenge & Disambiguation ] ──► [ Inline CONTEXT.md Update ]
                                                                 │
                                ┌────────────────────────────────┴────────────────────────────────┐
                                ▼                                                                 ▼
                     [ Domain Dictionary ]                                              [ Architectural Records ]
                     - Single-context: `CONTEXT.md`                                     - `docs/adr/NNNN-<slug>.md`
                     - Multi-context: `CONTEXT-MAP.md`                                  - Context, Decision, Consequences
ArtifactResponsibilityFormat Reference
Domain GlossaryCanonical terms, entity boundaries, invariantsskills/domain-modeling/CONTEXT-FORMAT.md
Architectural RecordIrreversible architectural choices & trade-offsskills/domain-modeling/ADR-FORMAT.md
Context MapBounded contexts across modular repositoriesCONTEXT-MAP.md

Step-by-Step Procedure (TWI)

Step 1: Detect Context Architecture & Glossary Baseline

  • Action: Check if a root CONTEXT-MAP.md exists (multi-context) or single CONTEXT.md / docs/adr/.
  • Key Point: Create glossary files lazily on the first resolved term.
  • Why: Multi-context systems require partitioning domain terms by bounded context to prevent collision.

Step 2: Challenge Fuzzy & Overloaded Language

  • Action: Intercept vague nouns (e.g. "account", "item", "process") and propose distinct canonical domain entities.
  • Key Point: Stress-test boundaries with concrete edge-case scenarios (e.g., "What happens during partial cancellation?").
  • Why: Ambiguous nouns lead to bloated database entities and tangled business logic.

Step 3: Verify Alignment Against Existing Codebase

  • Action: Search the codebase for entity names and check whether existing schemas agree with the user's description.
  • Key Point: Highlight discrepancies immediately: "The code cancels entire Orders, but you described partial cancellation. Which is correct?"
  • Inline Checklist:
    • Term verified against live database/code entities
    • Definition added to CONTEXT.md using standard format
    • Implementation details omitted from glossary

Step 4: Author Architectural Decision Records (ADRs)

  • Action: For decisions meeting the 3-point threshold, create docs/adr/NNNN-<slug>.md.
  • Key Point: Document Context, Decision, Status, and Consequences.
  • Why: Transparent ADRs prevent repetitive debates and document technical debt trade-offs.

Anti-Rationalization Guardrails

Tempting RationalizationBinding RuleEngineering Rationale
"I'll add database table schemas into CONTEXT.md."Forbidden. CONTEXT.md contains pure domain terms only.Coupling the domain glossary to DB schemas makes it obsolete upon migration.
"Let's write an ADR for every small choice (e.g. library helper)."Enforce the 3-point ADR threshold.Low-value ADRs clutter documentation and obscure truly critical architectural choices.
"The user used 'User' and 'Customer' interchangeably; I'll ignore it."Challenge and disambiguate overloaded terms immediately.Conflating distinct domain concepts creates severe authorization and modeling bugs.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free