zhuochun Domain Modeling
Build a problem-specific model that clarifies important decisions, rules, and behavior. Treat modeling as a learning loop across work, examples, code, data, operations, and change—not a universal taxonomy.
Preserve context and authority
- Start with required repository guidance, the disputed example or workflow, its language, and relevant existing owners. Recover their accepted decisions before proposing another model.
- Locate the changed-surface owner and the owner of coherent behavior, state, or meaning before proposing another model. Reconcile implementation with work, language, and outcomes.
- Default to analysis and proposal. Update documentation or code only when the user requests it, and preserve established artifact names and locations.
- Treat stakeholder prescriptions, code, schemas, and services as evidence, not sole authority. Preserve mandated constraints and rationale.
- Mark consequential material confirmed, inferred, assumed, proposed, or unresolved; attach evidence locators when available.
- Record disagreement, context-specific meanings, and missing perspectives. Do not force one enterprise-wide definition where several precise local models are healthier.
- Keep legal, privacy, fairness, safety, and distributional judgments with accountable owners. Expose category meaning and revision authority without certifying those judgments.
- Keep semantic context, code module, data authority, deployable service, failure domain, and team ownership distinct unless evidence justifies aligning them.
Modeling workflow
- Recover the problem. Translate requested screens, fields, services, schemas, rules, or technologies into outcomes, decisions, constraints, examples, invariants, and success or failure. Keep implementation as one candidate unless constrained.
- Bound the investment. Name the workflow or decision, owners, and horizon. Model intensively only where meaning, rules, lifecycle, or translation is disputed or repeatedly costly. If semantics and ownership are settled, return the smallest owner finding, rule, or implementation route. A no-modeling result cites changed-surface and preserved-state owners, sufficiency evidence, and important non-changes. Never create a second semantic owner; state exclusions.
- Gather discriminating evidence. Compare the competing meanings against real work and relevant code, data, interfaces, tests, or stakeholder accounts. Expand sources when disagreement, missing perspectives, or hidden state could change the model. Reuse current evidence; stop expanding when it cannot change meaning, boundaries, confidence, or an unresolved obligation. Preserve counterexamples and affected perspectives for consequential classification.
- Write operational principles. Trace each important concept from purpose through actors, state, actions, transitions, and observable outcome. Add edge scenarios for reversal, authorization, time, partial progress, failure, repair, and reporting when consequential.
- Generate and compare candidates. For consequential choices, create materially different lightweight models. Judge them by difficult decisions, workflows, operations, invariants simplified, omissions, new complexity, and awkward adjacent scenarios—not realism or completeness alone.
- When a candidate depends on identity, distinguish occurrence, content, semantic subject, version, and mutable locator. Challenge multiplicity, reorder, split or merge, edits, regeneration, deletion, and reappearance before claiming stability. Preserve provenance and unresolved identity policy rather than treating a hash or current key as universal identity.
- Diagnose model friction. Treat repeated exceptions, flag clusters, generic records, missing terms, awkward transitions, cross-cutting edits, inconsistency, and hidden-history rules as investigation prompts, not pattern mandates.
- Draw semantic boundaries and translations. State where vocabulary, rules, invariants, and authority remain coherent. At each edge, identify the foreign and local meanings, translation or deliberate conformance, contract, ownership, and power constraints. Describe the relationship actually evidenced; do not force a context-map label.
- When classifications determine what the system can recognize or act on, expose the selected objects, subjects, categories, and relations; excluded or ambiguous cases; affected perspectives; and contest or revision authority. Treat ambiguity as possible boundary evidence, not automatically bad data.
- Choose enforcement proportionately. Use conversation, documentation, modules, ownership, private persistence, interfaces, or isolation as needed. Account for coordination, translation, latency, failure, observability, and operating cost. Route deployable, data, failure, or team boundaries to
$service-boundary-design. - Express and renew. Reflect stable concepts in names, types, events, tests, modules, APIs, and data authority where useful. Record alternatives and revisit signals; use later change and failure as refinement evidence.
Route an accepted rule or state model to prototype-to-learn when hands-on driving could expose ambiguity, and an accepted workflow to architecture-surface-mapping when a shared experience-to-system walkthrough is missing. Keep disputed meaning and invariant authority here.
Return the smallest useful result: an evidence-backed no-modeling finding, compact principle, or selective model with alternatives, boundaries, translations, unresolved owner decisions, and revisit signals.
Read references/modeling-artifacts.md only when a facilitated session, model comparison, consequential classification, model-to-code expression decision, context boundary, or durable decision record is needed.
Quality gates
- The selective model names its problem, decision, or workflow.
- Modeling effort is justified by a material semantic question or friction; otherwise the changed-surface and preserved-behavior owners, sufficiency evidence, and smaller route are named.
- Concepts connect purpose, state, action, and outcomes; consequential choices compare scenarios and omissions.
- Materially different candidates require the smallest self-contained text comparison of concepts, invariants, state, action, authority, and translation. Mark evidence, proposals, unchanged commitments, and unresolved decisions.
- Identity-bearing models state what remains the same, what creates a new identity, and which transformations or duplicates break the proposed key.
- Language and rules reconcile with work, code, data, and operations or expose contradictions.
- Consequential classifications expose exclusions, affected perspectives, and contest or revision authority without taking adjacent legal, privacy, fairness, or safety decisions.
- Boundaries define precise meaning and foreign translation or conformance.
- Logical, code, data, deployment, failure, and team boundaries remain distinct.
- Enforcement balances integrity with relocated complexity.
- Consequential claims retain evidence labels; uncertainty, disagreement, migration gaps, and revisit signals persist.
Reject modeling theater
- Nouns are not automatically entities, tables are not the model, and contexts are not services.
- Reject behavior-free glossaries, universal enterprise models, and label-only context maps.
- Do not naturalize encoded categories as discovered facts, call every state change a domain event, or wrap every primitive in a value object.
- Reconcile experts, code, schemas, and service ownership; preserve meaningful local terminology and translate meaning, not shape.
- Physical separation cannot repair incoherence, and elegance alone cannot justify rewriting without compatibility, migration, and operational evidence.