# 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:

```text
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](design-status-template.md) as the base template.

## Workflow-level artifacts

Store workflow-slice documents in:

```text
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](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](../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.