typescript-decompiler/docs/reference/design-artifact-structure.md

Design Artifact Structure

This is the current artifact layout for real feature work. Use this structure for feature discovery, bounded-context decomposition, workflow-slice design, implementation tracking, and handoff between agents or humans.

Top-level idea

• Feature discovery happens once per feature.
• Decomposition maps the feature into bounded contexts and workflow slices.
• Slice design and implementation happen one workflow slice at a time.
• F# blueprint artifacts are the frozen contract that implementation translates from.

Feature-level artifacts

Store feature-level documents in:

design/feature/<feature-slug>/
├── discovery.md
├── design.md
└── status.md

discovery.md

Capture:

• feature story
• commands and events at feature level
• business rules and invariants at feature level
• edge cases at feature level
• candidate bounded contexts
• candidate workflow slices
• feature-level shared language notes

design.md

Capture:

• bounded context inventory
• feature-step to workflow-slice map
• cross-context handoffs
• recommended slice order
• orchestration notes
• open questions

status.md

Track:

• current feature phase
• current workflow slice
• decomposition completion
• per-slice gate status
• blockers and handoff notes

Use design-status-template.md as the base template.

Workflow-level artifacts

Store workflow-slice documents in:

design/workflows/<bounded-context-slug>/
├── shared-language.md
├── shared-model.fs            # optional, when the context has reusable F# domain pieces
└── <workflow-slug>/
    ├── 01-decomposition.md
    ├── 02-discovery.md
    ├── 03-core-sketch.md
    └── 04-blueprint.fs

shared-language.md

Capture bounded-context-local ubiquitous language:

• what the context owns
• preferred terms
• rejected synonyms
• notes about overlap with project-wide language in shared-language.md

01-decomposition.md

Capture:

• owning bounded context
• trigger
• purpose and success outcome
• inputs owned by this context
• observed inputs from other contexts
• downstream handoffs
• dependencies on other slices
• explicit note that decision logic stays inside the owning context

02-discovery.md

Capture:

• happy path
• edge cases
• business rules and invariants
• decisions owned by this context
• handoff assumptions
• open questions

03-core-sketch.md

Capture:

• command
• required owned state
• observed external inputs
• pseudo policy signature
• events
• boundary notes about what remains feature-level orchestration

04-blueprint.fs

This is the frozen F# contract for one workflow slice. It should include:

• domain primitives
• commands
• events
• states / aggregates
• decide
• apply
• workflow contract signature

Rules of use

• One workflow slice belongs to one bounded context.
• No cross-context decision logic belongs inside a workflow slice.
• Cross-context behavior belongs in feature-level handoff and orchestration notes.
• Shared language should exist both globally and per bounded context.
• Implementation should proceed one slice at a time from the frozen F# blueprint.

Relationship to the by-hand docs

The ../by-hand/README.md material keeps the simpler 5-phase human practice flow. Use that to build judgment. Use this page for the actual repository artifact structure.