extract-domain-model

name	extract-domain-model
description	Extract a reusable domain model from an approved brief or problem framing artifact. Use when Codex needs actors, use cases, entities, value objects, business rules, invariants, constraints, and canonical terms distilled into a stable domain artifact before architecture or contract design. Do not use for API design, module design, or implementation.

Extract Domain Model

Goal

Turn business intent into a precise domain artifact that later skills can use without rediscovering the core language of the system.

Read Shared Contract Reference before producing the artifact.

Trigger boundary

• Use after a brief or framing review is available and the next task is domain modeling.
• Do not use for architecture design, interface contracts, or code generation.

Required input

• Required: approved brief, problem-framing-review, or equivalent requirements artifact with metadata showing approval_status: approved
• Optional: existing terminology, product notes, policies, examples, legacy behavior

Refusal and blocked policy

• Model business concepts, not controllers, repositories, transports, or frameworks.
• Prefer explicit uncertainty over invented domain rules.
• Keep technical constraints only when they materially shape the domain.
• Return BLOCKED when the upstream requirements artifact is missing or clearly not approved.
• Return BLOCKED when the task is actually architecture design or contract design.

Workflow

1. Identify the primary actors and their goals.
2. Normalize overloaded terminology into canonical TERM-* entries.
3. Derive UC-* use cases and the outcomes each actor expects.
4. Extract entities, value objects, aggregates, or equivalent domain concepts.
5. Capture INV-* business rules, invariants, TRANS-* state transitions, and hard constraints.
6. Separate domain concerns from external systems and infrastructure.
7. Record open questions that block accurate modeling.

Output contract

Write domain-model.md or return equivalent Markdown using this structure:

# Domain Model

## Artifact Metadata
- artifact_id:
- artifact_type: domain-model
- artifact_status: draft | current | superseded
- approval_status: pending_review | approved | changes_required | rejected
- approved_by_gate_profile: none | domain-model
- gate_report_ref: none | <ref>
- upstream_artifact_refs:

## Domain Summary
...

## Canonical Terms
| term_id | term | meaning | replaces_or_disambiguates |
| --- | --- | --- | --- |

## Actors
| actor_id | actor | goal | notes |
| --- | --- | --- | --- |

## Use Cases
| use_case_id | primary_actor_id | trigger | preconditions | successful_outcome | invariant_ids |
| --- | --- | --- | --- | --- | --- |

## Entities
- entity_id:
- name:
  purpose:
  core_attributes:

## Value Objects
- value_object_id:
- name:
  meaning:
  validation_rules:

## Business Rules
- rule_id: BR-*
- rule:
- rationale:

## Invariants
- invariant_id: INV-*
- statement:
- touched_by_use_case_ids:

## State Transitions
- transition_id: TRANS-*
- entity_or_process:
  allowed_transitions:
  forbidden_transitions:
  protected_by_invariant_ids:

## Constraints
- constraint:
- type: policy | legal | legacy | operational | product
- impact_on_modeling:

## Outside The Domain
- external_system:
  reason_it_is_outside:

## Open Questions
- ...

Quality bar

• Ensure every major use case maps to at least one actor and one domain concept.
• Use consistent terminology throughout the artifact.
• Make invariants testable and specific.
• Keep infrastructure language out of the model unless it is truly a domain constraint.
• Prefer BLOCKED over guessed invariants when the upstream requirements are underspecified.
• Initialize artifact metadata with approval_status: pending_review until a gate or approver marks it otherwise.