Skip to content

Devlight/UMADE-BA-REPO

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

40 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

UMADE — BA Pipeline

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.


Project Overview

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.

Spec format

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.

Scope of this repo

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).


Files in this folder

Pipeline prompts

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

Standalone prompts

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

Pipeline order

_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)

How to run each step

Each step runs in a fresh Claude Code chat. Reference files with @path/to/file.md. Finish with Save output to <path>.


Phase 0 — Project bootstrap (one-time)

ba-0.1 — Handoff Brief

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

ba-0.2 — Open Questions register (initial run after ba-0.1)

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

ba-0.2 — Register (Mode A — after any pipeline step or session)

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

ba-0.2 — Resolve (Mode B — when answers are available)

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

Phase 1 — Domain foundation

After every step in this phase, run ba-0.2 Mode A against the new artifact.

ba-1.0 — Glossary

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

ba-2.0 — Business Rules

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

ba-2.2 — Non-Functional Requirements

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

ba-3.0 — Role Matrix

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

Gate 1 — Domain Foundation

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

Phase 2 — Entity map and backlog

ba-4.0 — Entity Map

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

ba-5.0 — Functional Backlog

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

Gate 2 — Backlog Traceability

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

Phase 3 — Feature specs

One backlog row per chat. Specify Story Mode every time (Full / Backend-only / Discovery).

ba-6.0 — Feature Spec

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

spec-oq-resolver — Self-resolve pass

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.

Gate 3 — Spec Traceability

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

Gate 4 — Spec Integrity

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

Gate 5 — Cross-Spec Consistency (optional)

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

Gate 6 — Design ↔ Spec Consistency (optional)

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

Steady state — continuous backlog growth

Once bootstrap is complete, new inputs are propagated through the cascade. Run only the steps the new input actually affects.

Trigger → first prompt

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

The cascade

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

Backlog operations

Add a new row

  1. Add the row to 5-functional-backlog.md — assign the next F-X.Y ID
  2. Run Gate 2
  3. Run ba-6.0, then spec-oq-resolver, then Gates 3 + 4

Retire a row (removed, split, superseded)

  1. Add a Retired Features comment block at the bottom of 5-functional-backlog.md — record date, reason, replacement ID(s)
  2. If a spec exists, move it to specs/_retired/ — never delete
  3. Update Depends On in any rows that referenced the retired ID
  4. Never reuse a retired ID

Update an existing spec (OQ resolved, scope change)

  1. Get the answer from a session debrief or explicit client decision
  2. Run ba-0.2 Mode B with: OQ-ID: verbatim answer
  3. Run spec-oq-resolver close-out pass per the regeneration plan
  4. Re-run Gates 3 + 4
  5. Commit spec + gate reports + updated 0.2-open-questions.md together

Maintain the release log

After any commit that bumps an artifact version, adds or retires a spec, or changes scope:

  1. Open RELEASE-NOTES.md in the repo root (create from release-notes-standard.md if absent)
  2. Add entries for every changed artifact ID using the tag conventions in release-notes-standard.md
  3. Bump the release version per vMAJOR.MINOR.PATCH rules
  4. Commit RELEASE-NOTES.md in the same commit as the artifact files it describes

ID reference

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

Authority per concern

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

What not to do

  • 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.2 Mode B
  • Don't copy BR text into specs — reference by BR-DOMAIN-NNN only
  • Don't add glossary terms inside specs or BRs — new terms go through ba-1.0 first
  • Don't skip spec-oq-resolver before Gates 3 + 4 — it produces false positives in Gate 3 Check B3
  • Don't run ba-0.2 Mode A against a spec before spec-oq-resolver — it pollutes the register with determinate-answer questions
  • Don't mark an OQ Decision by: BA for product-specific calls — pricing, eligibility, copy, scope, channel availability, regulatory deviations are always Business; stack-specific library / protocol / infra choices are always Dev
  • Don't reuse a retired F-X.Y ID — 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 through ba-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

About

No description, website, or topics provided.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors