BA artifacts repository for the UMADE project. This repo contains the full set of Claude-generated BA artifacts and the prompts that produce them — no application code lives here.
UMADE — a multi-brand e-commerce aggregator and premium marketplace for Ukrainian designer fashion brands, providing a unified discovery experience for end users and attribution-based monetization for participating sellers.
Target market: Ukraine (MVP); European expansion in roadmap — USD billing currency, Europe/Kyiv timezone, GDPR regulatory baseline.
Surfaces: Storefront (Next.js 16, App Router, customer-facing), Vendure Admin UI (UMade operators), Brand Catalogue Sync (automated Shopify integration), Attribution & Billing Plugin (monetization backend).
Feature areas: E-1 Seller Integration · E-2 Product Catalog · E-3 Click Tracking & Attribution · E-4 Storefront CMS & Navigation · E-5 Brand Management · E-6 Product Listing · E-7 Product Detail · E-8 Collections · E-9 Search · E-10 SEO.
Specs live in docs/ba/artifacts/specs/ as feature-area folders fa-NN-<slug>/ containing f-X.Y-<slug>.md files produced by the ba-6.0 pipeline. They follow the ba-6.1-feature-spec-template.md structure with explicit traceability to BR-DOMAIN-NNN, R-SLUG-NN, GL-NNN IDs.
Pre-pipeline specs inherited from the discovery phase live in specs/_old-formatted/ and are treated as authoritative source material — do not invent IDs to fit them. Retired specs live in specs/_retired/ and are never deleted.
This repo contains only BA artifacts (specs, glossary, business rules, role matrix, entity map, backlog, NFR) and the Claude prompts that generate them — no application code. All artifact content is written in English; source materials in _sources/ stay in their original language (Ukrainian, English, mixed).
| File | Produces | Key IDs |
|---|---|---|
ba-0.1-handoff-brief.md |
0.1-handoff-brief.md |
OQ-HB-NNN |
ba-0.2-open-questions.md |
0.2-open-questions.md |
OQ-{ORIGIN}-NNN |
ba-1.0-glossary.md |
1-glossary.md |
GL-NNN, TI-NNN |
ba-2.0-business-rules.md |
2-business-rules.md |
BR-DOMAIN-NNN, BR-GAP-NNN |
ba-2.2-nfr.md |
2.2-nfr.md |
NFR-NNN |
ba-3.0-role-matrix.md |
3-role-matrix.md |
R-SLUG-NN, RES-NN, ACT-NN, RM-GAP-NNN |
ba-4.0-entity-map.md |
4-entity-map.md |
DM-GAP-NNN |
ba-5.0-functional-backlog.md |
5-functional-backlog.md |
F-X.Y |
ba-6.0-feature-spec.md |
specs/fa-NN-<slug>/f-X.Y-<slug>.md |
EC-NN, AC-PREFIX-NN |
ba-6.1-feature-spec-template.md |
reference template used by ba-6.0 |
— |
These run any time during the project — they are not numbered pipeline steps and have no fixed position in the dependency graph.
| File | Purpose |
|---|---|
session-debrief.md |
After every recorded discovery or design session — produces _sources/sessions/session-YYYY-MM-DD-{slug}.md |
spec-oq-resolver.md |
Immediately after saving a fresh spec — closes BA-resolvable OQs in Section 2.7 in place; run before Gates 3 + 4 |
ba-3.2-qg-1-domain-foundation.md |
Gate 1 — run after ba-3.0, before ba-4.0 |
ba-5.2-qg-2-backlog-traceability.md |
Gate 2 — run after ba-5.0, before any ba-6.0 |
ba-6.2-qg-3-feature-spec-traceability.md |
Gate 3 — run after spec-oq-resolver, alongside Gate 4 |
ba-6.3-qg-4-feature-spec-integrity.md |
Gate 4 — run after spec-oq-resolver, alongside Gate 3 |
ba-6.4-qg-5-cross-spec-consistency.md |
Gate 5 (optional) — run on 2+ specs sharing a contract |
ba-6.5-qg-6-design-spec-consistency.md |
Gate 6 (optional) — run on a (spec, Figma) pair with a UI surface |
_sources/ (client · presale · sessions · dev · third-party)
│
▼
ba-0.1 ──► 0.1-handoff-brief.md
│
▼
ba-0.2 ──► 0.2-open-questions.md ◄── run after EVERY step and EVERY session
│
▼
ba-1.0 ──► 1-glossary.md
│
├──► ba-2.0 ──► 2-business-rules.md
│ │
│ ▼
│ ba-3.0 ──► 3-role-matrix.md
│ │
│ │ [Gate 1 — Domain Foundation]
│ ▼
│ ba-4.0 ──► 4-entity-map.md
│ │
│ ▼
│ ba-5.0 ──► 5-functional-backlog.md
│ │
│ │ [Gate 2 — Backlog Traceability]
│ │
│ │ (one call per F-X.Y backlog row)
│ ▼
│ ba-6.0 ──► specs/fa-NN-<slug>/f-X.Y-<slug>.md
│ │ (§2.7 OQs tagged Decision by: BA / Dev / Business)
│ ▼
│ spec-oq-resolver ← self-resolve pass (BA-resolvable OQs only)
│ ▼
│ ba-0.2 Mode A ← register surviving Dev / Business OQs
│ ▼
│ [Gate 3 — Spec Traceability] ──┐ run in parallel
│ [Gate 4 — Spec Integrity] ──┘
│ │
│ ▼
│ [stakeholder session → session-debrief → answers]
│ ▼
│ ba-0.2 Mode B (Resolve)
│ ▼
│ spec-oq-resolver ← close-out pass
│ ▼
│ [Gate 3 + Gate 4 re-run]
│ │
│ ├──► [Gate 5 — Cross-Spec Consistency] (optional)
│ ├──► [Gate 6 — Design ↔ Spec Consistency] (optional)
│ ▼
│ Status: Approved → dev handoff
│
└──► ba-2.2 ──► 2.2-nfr.md (parallel sibling of ba-2.0)
Each step runs in a fresh Claude Code chat. Reference files with @path/to/file.md. Finish with Save output to <path>.
Generate the handoff brief from presale and discovery materials.
@docs/ba/prompts/ba-0.1-handoff-brief.md
@docs/ba/_sources/presale/
@docs/ba/_sources/client/
@docs/ba/_sources/_discovery-artifacts/
Save output to docs/ba/artifacts/0.1-handoff-brief.md
Register the initial open questions from the handoff brief.
@docs/ba/prompts/ba-0.2-open-questions.md
Handoff Brief:
@docs/ba/artifacts/0.1-handoff-brief.md
Save output to docs/ba/artifacts/0.2-open-questions.md
Register new open questions from [artifact name].
@docs/ba/prompts/ba-0.2-open-questions.md
Current register:
@docs/ba/artifacts/0.2-open-questions.md
New artifact to scan:
@docs/ba/artifacts/<artifact>.md
Save output to docs/ba/artifacts/0.2-open-questions.md
Resolve the following open questions.
@docs/ba/prompts/ba-0.2-open-questions.md
Current register:
@docs/ba/artifacts/0.2-open-questions.md
Resolved questions:
OQ-HB-001: <verbatim answer>
OQ-FS-003: <verbatim answer>
Save output to docs/ba/artifacts/0.2-open-questions.md
After every step in this phase, run ba-0.2 Mode A against the new artifact.
Generate the glossary.
@docs/ba/prompts/ba-1.0-glossary.md
Handoff Brief:
@docs/ba/artifacts/0.1-handoff-brief.md
Source materials:
@docs/ba/_sources/presale/
@docs/ba/_sources/sessions/
@docs/ba/_sources/_discovery-artifacts/
@docs/ba/_sources/dev/
Save output to docs/ba/artifacts/1-glossary.md
Generate the business rules register.
@docs/ba/prompts/ba-2.0-business-rules.md
Glossary:
@docs/ba/artifacts/1-glossary.md
Source materials:
@docs/ba/artifacts/0.1-handoff-brief.md
@docs/ba/_sources/presale/
@docs/ba/_sources/sessions/
@docs/ba/_sources/_discovery-artifacts/
@docs/ba/_sources/dev/
Save output to docs/ba/artifacts/2-business-rules.md
Parallel sibling of ba-2.0 — runs off the same sources; re-run after any session that adds performance, security, reliability, or compliance statements.
Extract NFRs.
@docs/ba/prompts/ba-2.2-nfr.md
Handoff Brief:
@docs/ba/artifacts/0.1-handoff-brief.md
Session debriefs:
@docs/ba/_sources/sessions/
Business Rules (recommended):
@docs/ba/artifacts/2-business-rules.md
Dev docs:
@docs/ba/_sources/dev/
Save output to docs/ba/artifacts/2.2-nfr.md
Generate the role matrix.
@docs/ba/prompts/ba-3.0-role-matrix.md
Glossary:
@docs/ba/artifacts/1-glossary.md
Business Rules:
@docs/ba/artifacts/2-business-rules.md
Handoff Brief:
@docs/ba/artifacts/0.1-handoff-brief.md
Save output to docs/ba/artifacts/3-role-matrix.md
Run after ba-3.0. Block on High findings.
Run Gate 1 against the domain foundation artifacts.
@docs/ba/prompts/ba-3.2-qg-1-domain-foundation.md
Glossary:
@docs/ba/artifacts/1-glossary.md
Business Rules:
@docs/ba/artifacts/2-business-rules.md
Role Matrix:
@docs/ba/artifacts/3-role-matrix.md
Save output to docs/ba/artifacts/gate1-report.md
Generate the entity map.
@docs/ba/prompts/ba-4.0-entity-map.md
Glossary:
@docs/ba/artifacts/1-glossary.md
Business Rules:
@docs/ba/artifacts/2-business-rules.md
Role Matrix:
@docs/ba/artifacts/3-role-matrix.md
Source materials:
@docs/ba/_sources/dev/
Save output to docs/ba/artifacts/4-entity-map.md
Generate the functional backlog.
@docs/ba/prompts/ba-5.0-functional-backlog.md
Glossary:
@docs/ba/artifacts/1-glossary.md
Business Rules:
@docs/ba/artifacts/2-business-rules.md
Role Matrix:
@docs/ba/artifacts/3-role-matrix.md
Entity Map:
@docs/ba/artifacts/4-entity-map.md
Handoff Brief:
@docs/ba/artifacts/0.1-handoff-brief.md
Save output to docs/ba/artifacts/5-functional-backlog.md
Run after ba-5.0. Block on High findings.
Run Gate 2 against the backlog.
@docs/ba/prompts/ba-5.2-qg-2-backlog-traceability.md
Functional Backlog:
@docs/ba/artifacts/5-functional-backlog.md
Glossary:
@docs/ba/artifacts/1-glossary.md
Business Rules:
@docs/ba/artifacts/2-business-rules.md
Role Matrix:
@docs/ba/artifacts/3-role-matrix.md
Save output to docs/ba/artifacts/gate2-report.md
One backlog row per chat. Specify Story Mode every time (Full / Backend-only / Discovery).
Run ba-6.0 for F-X.Y.
@docs/ba/prompts/ba-6.0-feature-spec.md
Glossary:
@docs/ba/artifacts/1-glossary.md
Business Rules:
@docs/ba/artifacts/2-business-rules.md
NFR:
@docs/ba/artifacts/2.2-nfr.md
Entity Map:
@docs/ba/artifacts/4-entity-map.md
Role Matrix:
@docs/ba/artifacts/3-role-matrix.md
Story Mode: Full
Backlog row (paste only the F-X.Y row):
| F-X.Y | Feature name | … |
Traceability row (from gate2-report.md, optional but recommended):
| F-X.Y | Feature name | BR-XXX-NNN | R-YYY-NN | GL-NNN | Size | Crit. path | BA Status |
Save output to docs/ba/artifacts/specs/fa-NN-<slug>/f-X.Y-<slug>.md
Run immediately after saving a fresh spec, before Gates 3 + 4. Do not skip this step.
Self-resolve pass for F-X.Y.
@docs/ba/prompts/spec-oq-resolver.md
Spec:
@docs/ba/artifacts/specs/fa-NN-<slug>/f-X.Y-<slug>.md
Glossary:
@docs/ba/artifacts/1-glossary.md
Business Rules:
@docs/ba/artifacts/2-business-rules.md
NFR:
@docs/ba/artifacts/2.2-nfr.md
Open questions register:
@docs/ba/artifacts/0.2-open-questions.md
Update the spec in place and update 1-glossary.md / 2-business-rules.md / 2.2-nfr.md / 0.2-open-questions.md as needed.
After the self-resolve pass, run ba-0.2 Mode A against the updated spec to register surviving Dev and Business OQs into 0.2-open-questions.md.
Run Gate 3 against F-X.Y spec.
@docs/ba/prompts/ba-6.2-qg-3-feature-spec-traceability.md
Spec:
@docs/ba/artifacts/specs/fa-NN-<slug>/f-X.Y-<slug>.md
Glossary:
@docs/ba/artifacts/1-glossary.md
Business Rules:
@docs/ba/artifacts/2-business-rules.md
Role Matrix:
@docs/ba/artifacts/3-role-matrix.md
Open Questions:
@docs/ba/artifacts/0.2-open-questions.md
Save output to docs/ba/artifacts/specs/fa-NN-<slug>/f-X.Y-<slug>-gate3.md
Run Gate 4 against F-X.Y spec.
@docs/ba/prompts/ba-6.3-qg-4-feature-spec-integrity.md
Spec:
@docs/ba/artifacts/specs/fa-NN-<slug>/f-X.Y-<slug>.md
CLAUDE-PROJECT.md:
@CLAUDE-PROJECT.md
Functional Backlog:
@docs/ba/artifacts/5-functional-backlog.md
Save output to docs/ba/artifacts/specs/fa-NN-<slug>/f-X.Y-<slug>-gate4.md
Run when 2+ specs share a domain entity, endpoint, or event topic.
Run Gate 5 across F-X.Y and F-A.B.
@docs/ba/prompts/ba-6.4-qg-5-cross-spec-consistency.md
Spec 1:
@docs/ba/artifacts/specs/fa-NN-<slug>/f-X.Y-<slug>.md
Spec 2:
@docs/ba/artifacts/specs/fa-MM-<slug>/f-A.B-<slug>.md
Save output to docs/ba/artifacts/gate5-report-fXY-fAB.md
Run on specs with a UI surface when a Figma design is available.
Run Gate 6 for F-X.Y.
@docs/ba/prompts/ba-6.5-qg-6-design-spec-consistency.md
Spec:
@docs/ba/artifacts/specs/fa-NN-<slug>/f-X.Y-<slug>.md
(Figma node is read from the spec's Design meta field via the Figma MCP.)
Save output to docs/ba/artifacts/specs/fa-NN-<slug>/f-X.Y-<slug>-gate6.md
Once bootstrap is complete, new inputs are propagated through the cascade. Run only the steps the new input actually affects.
| New input | First prompt |
|---|---|
Client document in _sources/client/ or _sources/third-party/ |
ba-0.2 Mode A |
| Recorded discovery session | session-debrief → then ba-0.2 Mode A |
Dev doc in _sources/dev/ (arch decision, RFC, implemented API spec) |
ba-0.2 Mode A; then re-run foundation prompts and/or ba-6.0 per affected spec |
| Standalone client decision (Slack, call note, OQ answer) | ba-0.2 Mode B |
| Step | Run when | Skip when |
|---|---|---|
ba-1.0 Glossary |
New domain term or redefined sense | No terminology change |
ba-2.0 Business Rules |
New behavior, policy, or constraint | No new behavior |
ba-2.2 NFR |
New performance / security / compliance / reliability constraint | No new quality attribute |
ba-3.0 Role Matrix |
New actor, role, resource, or permission shift | No role change |
| Gate 1 | Any of ba-2.0 / ba-2.2 / ba-3.0 ran |
Only ba-1.0 ran |
ba-4.0 Entity Map |
New entity, relationship, cardinality change, or invariant | No entity-level change |
ba-5.0 Functional Backlog |
New scope item | Input only refined an existing rule |
| Gate 2 | ba-5.0 ran |
ba-5.0 didn't run |
ba-6.0 + spec-oq-resolver + Gates 3+4 |
One run per new or updated F-X.Y |
No new or changed rows |
- Add the row to
5-functional-backlog.md— assign the nextF-X.YID - Run Gate 2
- Run
ba-6.0, thenspec-oq-resolver, then Gates 3 + 4
- Add a Retired Features comment block at the bottom of
5-functional-backlog.md— record date, reason, replacement ID(s) - If a spec exists, move it to
specs/_retired/— never delete - Update
Depends Onin any rows that referenced the retired ID - Never reuse a retired ID
- Get the answer from a session debrief or explicit client decision
- Run
ba-0.2Mode B with:OQ-ID: verbatim answer - Run
spec-oq-resolverclose-out pass per the regeneration plan - Re-run Gates 3 + 4
- Commit spec + gate reports + updated
0.2-open-questions.mdtogether
After any commit that bumps an artifact version, adds or retires a spec, or changes scope:
- Open
RELEASE-NOTES.mdin the repo root (create fromrelease-notes-standard.mdif absent) - Add entries for every changed artifact ID using the tag conventions in
release-notes-standard.md - Bump the release version per
vMAJOR.MINOR.PATCHrules - Commit
RELEASE-NOTES.mdin the same commit as the artifact files it describes
| Namespace | Format | Resets? |
|---|---|---|
| Glossary terms | GL-NNN |
No |
| Terminology issues | TI-NNN |
No |
| Business rules | BR-DOMAIN-NNN |
No |
| BR gaps | BR-GAP-NNN |
No |
| Entity map gaps | DM-GAP-NNN |
No |
| Roles | R-SLUG-NN |
No |
| Resources | RES-NN |
No |
| Special actions | ACT-NN |
No |
| Role matrix gaps | RM-GAP-NNN |
No |
| Features | F-X.Y |
No |
| Non-functional requirements | NFR-NNN |
No |
| Open questions | OQ-ORIGIN-NNN |
No |
| Edge cases | EC-NN |
Yes — per spec |
| Acceptance criteria | AC-PREFIX-NN |
Yes — per spec |
OQ origin codes: HB (handoff brief) · NF (NFR) · GL · BR · RM (role matrix) · DM (entity map) · WB (backlog) · FS (feature spec)
BR domain mnemonics registered for UMADE (3–5 uppercase chars; add new ones here and in CLAUDE-PROJECT.md before first use):
| Mnemonic | Domain | Status |
|---|---|---|
ATR |
Sales attribution (CPS) | ✅ in use |
BIL |
Billing, invoicing, disputes | ✅ in use |
BRD |
Brand management | ✅ in use |
CAT |
Product catalogue, categories, facets | ✅ in use |
CMS |
CMS content blocks and pages | ✅ in use |
COL |
Collections (UMade, Stylist, Look) | ✅ in use |
NAV |
Storefront navigation and menus | 🔒 reserved |
POP |
Popularity scoring | ✅ in use |
PPC |
Click tracking (Pay Per Click) | ✅ in use |
PRV |
Privacy, GDPR, data retention | ✅ in use |
SEL |
Seller integration and Shopify sync | ✅ in use |
SEO |
SEO, sitemaps, structured data | 🔒 reserved |
SRC |
Search and filtering | ✅ in use |
STF |
Storefront display and rendering rules | ✅ in use |
VAL |
Input validation rules | 🔒 reserved |
Role slugs registered for UMADE (2–4 uppercase chars; add new ones here and in CLAUDE-PROJECT.md before first use):
| Slug | Role | ID in role matrix |
|---|---|---|
UA |
UMade Admin | R-UA-01 |
SU |
Storefront User (anonymous / guest) | R-SU-01 |
SYS |
System / automated process | R-SYS-01 |
| Concern | File | Reference format |
|---|---|---|
| Term definitions | 1-glossary.md |
GL-NNN |
| Business behavior and constraints | 2-business-rules.md |
BR-DOMAIN-NNN |
| Entity relationships, ownership, integrity invariants | 4-entity-map.md |
entity name, INV-N, DM-GAP-NNN |
| Who may do what | 3-role-matrix.md |
R-SLUG-NN, RES-NN, ACT-NN |
| Feature scope and sizing | 5-functional-backlog.md |
F-X.Y |
| Quality attributes | 2.2-nfr.md |
NFR-NNN |
| Field contracts | spec Section 5 | field name |
| Unresolved decisions | 0.2-open-questions.md |
OQ-ORIGIN-NNN |
| Session answers and facts | _sources/sessions/ |
session file + timestamp |
| Notation and format conventions | CLAUDE-PROJECT.md |
section name |
| Project changelog | RELEASE-NOTES.md |
vMAJOR.MINOR.PATCH |
- Don't paste prompt contents inline — use
@docs/ba/prompts/<prompt>.md - Don't continue a previous chat for a new step — fresh chat every time
- Don't answer open questions by editing artifact files — go through
ba-0.2Mode B - Don't copy BR text into specs — reference by
BR-DOMAIN-NNNonly - Don't add glossary terms inside specs or BRs — new terms go through
ba-1.0first - Don't skip
spec-oq-resolverbefore Gates 3 + 4 — it produces false positives in Gate 3 Check B3 - Don't run
ba-0.2Mode A against a spec beforespec-oq-resolver— it pollutes the register with determinate-answer questions - Don't mark an OQ
Decision by: BAfor product-specific calls — pricing, eligibility, copy, scope, channel availability, regulatory deviations are alwaysBusiness; stack-specific library / protocol / infra choices are alwaysDev - Don't reuse a retired
F-X.YID — the next Y continues from the last assigned - Don't edit prompt files to record project-specific decisions — per-project conventions go in
CLAUDE-PROJECT.md, decisions go throughba-0.2 - Don't skip Gate 3 or Gate 4 before dev handoff — never hand off a spec with unresolved High findings
- Don't put Vendure-native capabilities into specs as custom work — check Vendure's built-in feature set before scoping any commerce-layer requirement (see
CLAUDE-PROJECT.md§ Platform awareness) - Don't register a new BR mnemonic or role slug without adding it to both this file and
CLAUDE-PROJECT.md