Skip to content

docs(core): define constructive domain modeling - #1207

Open
phernandez wants to merge 1 commit into
mainfrom
codex/constructive-domain-modeling
Open

docs(core): define constructive domain modeling#1207
phernandez wants to merge 1 commit into
mainfrom
codex/constructive-domain-modeling

Conversation

@phernandez

Copy link
Copy Markdown
Member

Why

Basic Memory's existing style guidance favored explicit types and fail-fast control flow, but it
did not name a consistent method for replacing procedural validation and expected-outcome
exceptions with types that describe the states the product actually supports.

Issue #1205 tracks focused, behavior-preserving refactor slices. This PR lands the shared
vocabulary and authoring/review rules first so later implementation work has a concrete design
standard.

What Changed

  • Define Constructive Domain Modeling as the preferred design method in
    docs/ENGINEERING_STYLE.md.
  • Describe products of required fields, closed unions, exhaustive consumers, total functions,
    and trusted boundary parsing.
  • Expand .agents/skills/pythonic-code/SKILL.md so Write, Refactor, and Review modes identify
    high-payoff constructive modeling opportunities.
  • Clarify the boundary between expected domain outcomes and truly exceptional failures.

Implementation Details

  • Frozen dataclasses and Python 3.12 unions are the default internal domain tools; Pydantic
    remains the validation and serialization model at API, CLI, MCP, configuration, and persistence
    boundaries.
  • Plain typed values and functions remain the default. Universal Result wrappers, effect
    runtimes, and wrapper-only identifiers require a demonstrated benefit rather than becoming a
    project-wide convention.
  • Persisted and compatibility shapes may remain broad while a boundary parser constructs a safer
    internal value. The guide requires tracing writers and serialized forms before narrowing those
    schemas.
  • This PR changes documentation and agent guidance only; it adds no runtime dependency or product
    behavior change.

Testing

Automated

  • uv run python /Users/phernandez/.codex/skills/.system/skill-creator/scripts/quick_validate.py .agents/skills/pythonic-code: passed.
  • just -f .agents/skills/pythonic-code/justfile validate: all three eval definitions, fixtures,
    runner lint, and formatting passed.
  • just -f .agents/skills/pythonic-code/justfile eval-dry-run: all three paired eval cases
    resolved successfully.
  • just fast-check: ruff fixes/checks, formatting, and ty type checking passed.
  • git diff --check origin/main...HEAD: passed.

Manual

Risks / Follow-ups

Related to #1205.

Signed-off-by: phernandez <paul@basicmachines.co>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant