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

Design Artifact Template

Use this template when drafting a design manually or when asking an LLM to produce a design artifact for review.

1. Story

Write the business situation in plain language.

A <role> attempts to <action>.
If <condition>, it succeeds.
If <condition>, it fails.

2. Event storming

Command

<ImperativeVerbNoun>

Timeline

Events

<SuccessEvent>
<FailureEvent>

3. Core sketch

Write the first policy sketch with rough concepts if needed.

decide : NeededInput -> NeededState -> Result<SuccessEvent, FailureEvent>

Then rewrite it using domain-specific concepts.

4. Domain model

Primitives

type ExampleId = string

Compound objects

type Example = {
  Id: ExampleId
}

State variants

type ActiveExample = { Id: ExampleId }
type ArchivedExample = { Id: ExampleId }

type ExampleState =
  | Active of ActiveExample
  | Archived of ArchivedExample

Events

type ExampleSucceeded = { Id: ExampleId }
type ExampleRejected = { Reason: RejectionReason }

5. Final contract

decide : Input -> State -> Result<SuccessEvent, FailureEvent>
apply : State -> SuccessEvent -> State
workflow : InputId -> Effect<Response>

6. Shared language and naming decisions

Record the canonical words for this feature so design and code stay consistent. If a term is project-wide rather than feature-local, also add it to docs/reference/shared-language.md.

Canonical terms

• <Preferred term>: short definition
• <Preferred term>: short definition

Rejected synonyms

• Use <Preferred term>, not <Rejected term>
• Use <Preferred term>, not <Rejected term>

Naming grammar for this feature

• Commands use: <ImperativeVerbNoun>
• Events use: <PastTenseFact>
• States / objects use: <DomainNoun>
• Workflow names use: <verbNoun>

7. Reviewer notes

Document any assumptions, open domain questions, or naming choices the reviewer should inspect.