Artifacts: What Each File Does
MOMENTUM uses several artifact types. This page explains what each is for, what it should contain, and what it should not.
Core Artifacts
1. product-strategy.md – The Strategy Spine
Role: The condensed specification of the product. It is the authoritative, high-level summary of what the product does and why. A human should be able to read it and get a clear understanding of the product's purpose, scope, and behavior.
Analogy: If your product were a scientific paper, the strategy would be the Abstract.
Example: - Strategy says: "Images can be exported as JPG and PNG."
Content: | Must contain | Must NOT contain | |-------------|------------------| | Problem and target users | Detailed rationale for every decision | | Goals and desired outcomes | Granular technical details | | High-level scope and non-goals | Exhaustive lists of edge cases | | Core constraints & assumptions | Full research transcripts or raw data | | Key success metrics | Implementation-level user flows |
2. product-evidence.md – The Detailed Rationale
Role: The detailed rationale that underpins the strategy. If strategy is the "what" and "why," evidence is the exhaustive proof. It provides the full context, data, research, and trade-offs that justify the statements made in the strategy.
Analogy: If your product were a scientific paper, the evidence would be the full text with all its data, citations, and appendices.
Example:
- Evidence adds: "JPG export must support user-selectable quality/compression settings (60%, 80%, 100%). We rejected WEBP format due to low user demand in research (see discovery/format-research.md)."
Content:
| Must contain | Must NOT contain |
|-------------|------------------|
| Expanded rationale behind strategic decisions | High-level strategy statements (these belong in product-strategy.md) |
| Summaries of user research with links to originals | Full, un-summarized interview transcripts |
| Data, metrics, and experiment results with interpretation | Unverified claims or raw data without context |
| Trade-offs considered and options rejected | |
| Core user flows and behavioral grounding | |
| Enough technical detail to ensure rebuildability | |
3. /delivery/epic-*/epic-[name].md – Strategic Capabilities
Folder Structure:
Stories live inside epic folders. One folder per epic, containing the epic file and all its stories:
/delivery
/epic-001-auth
epic-001-auth.md
story-ep001-001.md
story-ep001-002.md
/epic-002-onboarding
epic-002-onboarding.md
story-ep002-001.md
story-ep002-002.md
story-ep002-003.md
Role:
Translate strategy into a concrete, user-visible capability.
| Must contain | May include | Must NOT contain |
|---|---|---|
| Problem and context | Simple Mermaid flowcharts or sequence diagrams | Task breakdowns |
| Functional scope and non-scope | Only if they add clarity beyond text | Detailed technical implementation |
| Key user flows and edge cases | Full UI designs | |
| Risks and open questions | ||
| Links to related stories | ||
| Acceptance boundary for “done” |
When to update it:
- When strategy changes and this epic is affected
- As you learn more during development (refine scope, add edge cases)
- When you discover new risks
4. /delivery/epic-*/story-[name].md – Testable Increments
Purpose: Define a small, testable piece of user value that fits in 1–2 days of work.
Role:
Define a small, testable increment of user value.
| Must contain | May include | Must NOT contain |
|---|---|---|
| User story (As a / I want / So that) | Simple Mermaid diagrams | Sprint tasks |
| Acceptance criteria | Only if they clarify complex behavior | Refactoring notes |
| UX notes and edge cases | Technical jargon without explanation | |
| Dependencies | ||
| Status |
When to update it:
- While in development (clarifications, refinements)
- Never after it's shipped (treat implemented stories as immutable)
- If behavior needs to change later, create a new story
5. /discovery/* – Research and Context
Purpose: Capture research, learnings, and thinking that inform strategy but aren't part of strategy itself.
| Topic | Include (Must) | Exclude (Must Not) |
|---|---|---|
| Inputs | Interview notes, meeting notes, experiments, competitive scans | Final decisions disguised as notes |
| Exploration | Hypotheses, questions, partial findings | Polished narrative docs that belong in evidence |
| Links | References to impacted strategy or evidence sections | Duplicate summaries that drift |
| Characteristics | Scoped by topic or date; can be exploratory; becomes input to evidence or strategy refinement | |
| Governance | Can later be compressed or archived | Silent deletion without summarising into evidence |
When to use it:
- During discovery phases
- After experiments
- After major releases or retros
- Continuously (but organize it)
The Abstraction Rule: Information Belongs at the Right Level
This framework uses explicit abstraction levels. Information should belong to the layer where it's most useful, not be duplicated across all layers.
Strategy Layer
Only what's essential to define the product intent.
Examples:
- ✓ "We prioritize passwordless auth for power users"
- ✓ "Core auth methods: biometric, passwordless, password (legacy)"
- ✗ "CSS border radius 4px"
- ✗ "Detailed list of 47 edge cases"
Evidence Layer
Detailed rationale and supporting context.
Examples:
- Why passwordless? Research summaries and observed metrics
- Auth method comparison table (security, adoption, implementation cost)
- Simple diagrams that help explain behaviour
Epic Layer
Concrete capabilities and workflows.
Examples:
- User flows and edge cases
- Epic-level acceptance boundary
- Risks and assumptions to validate
Story Layer
Individual, testable increments.
Examples:
- One slice: “As a user with biometric enabled…”
- Acceptance criteria and test scenarios
Architecture and Design Layer
Implementation-specific details.
Examples:
- CSS, component APIs, database schema, third-party integrations
The Rule
If it's important to define the product, mention it in strategy at the right abstraction level. Everything else goes deeper.
- Rationale and detailed explanation → Evidence
- Workflows and edge cases → Epics
- Individual test cases → Stories
- Code and configuration → Architecture/Design
Relationships
product-strategy.md (SSOT)
|
v
Informs epics
|
|-- epic-001.md
|-- epic-002.md
|-- epic-003.md
|
v
Informs stories
|
|-- story-001.md
|-- story-002.md
|-- story-003.md
|
v
Implemented & shipped
|
v
Updates product-evidence.md
(if behaviour is surprising or strategically relevant)
|
v
May trigger update to product-strategy.md
(if assumptions are contradicted)
Artifact Lifecycle at a Glance
| Artifact | Created | Updated | Finalized | Archived |
|---|---|---|---|---|
| Strategy | Quarterly or major pivot | When production contradicts it | Never (only versions) | N/A |
| Evidence | Continuously | Every week or two | N/A | Can be compressed for history |
| Epic | When strategy supports it | While in development | When all stories shipped | Still readable; treated as reference |
| Story | Before dev starts | During dev (clarifications) | When shipped | Immutable; reference only |
| Discovery | During research | During research | Optionally (snapshot) | Archived for history |
Summary: The Right Tool for the Right Job
- Think about strategy →
product-strategy.md - Explain why strategy is true →
product-evidence.md - Group related capabilities → Epic
- Define one testable increment → Story
- Explore, research, learn →
/discovery/*