DOMAIN:REQUIREMENTS:SCOPE_ARCHITECTURE¶

OWNER: aimee (Scope Architect, Opus model) UPDATED: 2026-03-24 SCOPE: transforming scope briefs into functional specifications ZONE: SHARED (serves all teams, pre-team-assignment) MODEL: Opus (most capable, highest cost — justified by spec quality impact on entire pipeline)

PRINCIPLE: THE_SPEC_IS_THE_CONTRACT¶

RULE: the functional specification defines what gets built. Nothing more, nothing less. RULE: if it is not in the spec, it is not in scope. If it is in the spec, it must be built. RULE: ambiguity in the spec costs 10x to resolve during development. REASON: Aimee is the most expensive agent (Opus). But a $15 scoping session that produces an airtight spec saves $150 in rework downstream. Every subsequent agent (Anna, Alexander, Faye, developers) depends on spec quality.

AIMEE_INPUT: THE_SCOPE_BRIEF¶

Aimee receives Dima's Scope Brief containing: - Client profile (business, industry, team size) - Problem statement - Feature list (MVP / Phase 2 / Future) - Constraints (platform, integrations, compliance, timeline) - Competitive context

AIMEE_FIRST_ACTION: read the entire Scope Brief. Identify gaps before writing anything.

GAP_IDENTIFICATION_CHECKLIST¶

[ ] Is the problem statement clear and quantified?
[ ] Are MVP features distinguishable from Phase 2?
[ ] Are user roles defined (who uses the system)?
[ ] Are integration points specific (not just "connects to accounting")?
[ ] Are compliance requirements identified (GDPR at minimum for EU clients)?
[ ] Is the data model implied by the features clear?
[ ] Are there conflicting requirements?

IF_GAPS_EXIST: Aimee sends specific questions back to Dima for client follow-up. Maximum 2 round-trips before proceeding with assumptions (documented).

FUNCTIONAL_SPEC_STRUCTURE¶

DOCUMENT_OUTLINE¶

# Functional Specification: {Project Name}
## Client: {Client Name}
## Version: {1.0}
## Date: {date}
## Author: Aimee (Scope Architect)

### 1. Executive Summary
{3-5 sentences: what is being built, for whom, solving what problem}

### 2. User Roles
{Define every type of user with their permissions and goals}

### 3. Feature Specifications
{One section per feature, each with full detail}

### 4. Cross-Cutting Concerns
{Auth, i18n, a11y, performance, SEO — applies to all features}

### 5. Non-Functional Requirements
{Performance targets, uptime, data retention, scalability}

### 6. Integration Requirements
{External systems, APIs, data import/export}

### 7. Data Model Overview
{High-level entity relationships — not a database schema}

### 8. Out of Scope
{Explicitly listed items that are NOT part of this project}

### 9. Assumptions
{Things assumed true that were not explicitly confirmed by client}

### 10. Glossary
{Domain-specific terms the client uses}

FEATURE_DECOMPOSITION¶

FROM_SCOPE_BRIEF_TO_FEATURES¶

Dima's Scope Brief has features like "Order management system." Aimee decomposes this:

SCOPE BRIEF FEATURE: "Order management system"

AIMEE DECOMPOSITION:
├── F-001: Order Creation
│   ├── Create new order with client selection
│   ├── Add line items with product/service and quantity
│   ├── Calculate totals with tax
│   └── Save as draft or submit
├── F-002: Order List & Search
│   ├── Paginated order list with filters (status, date, client)
│   ├── Search by order number, client name, product
│   └── Sort by date, amount, status
├── F-003: Order Detail View
│   ├── Full order information display
│   ├── Order history / audit trail
│   └── Status progression visualization
├── F-004: Order Status Management
│   ├── Status workflow: Draft → Submitted → In Progress → Completed → Invoiced
│   ├── Status change with optional notes
│   └── Notification on status change (to assigned staff)
├── F-005: Order Editing
│   ├── Edit draft orders (full edit)
│   ├── Edit submitted orders (limited: notes, assignment)
│   └── Cancel order with reason
└── F-006: Client-Facing Order Status
    ├── Read-only view of order status
    ├── No login required (magic link or order number lookup)
    └── Mobile-responsive

DECOMPOSITION_RULES¶

RULE: each feature (F-nnn) must be independently demonstrable to the client. RULE: a feature should map to 1-5 screens in the UI. RULE: if a feature has more than 5 sub-features, it should be split into multiple features. RULE: features are the unit of client communication. WPs (Faye's domain) are the unit of execution.

ACCEPTANCE_CRITERIA_WRITING¶

FORMAT¶

Use Given-When-Then for behavioral criteria. Use declarative statements for constraint criteria.

### F-001: Order Creation

**Behavioral Criteria:**
- GIVEN a logged-in staff user
  WHEN they click "New Order"
  THEN they see a form with client selector, line item table, and totals

- GIVEN a user is creating an order
  WHEN they select a client
  THEN the client's address and contact info auto-populate

- GIVEN a user has added at least one line item
  WHEN they click "Save as Draft"
  THEN the order is saved with status "Draft" and appears in the order list

- GIVEN a user has added at least one line item
  WHEN they click "Submit"
  THEN the order status changes to "Submitted" and the assigned staff is notified

**Constraint Criteria:**
- Order number is auto-generated: ORD-{YYYY}-{sequential}
- Line item quantity must be positive integer
- Line item price must be non-negative decimal with 2 decimal places
- Tax rate is configurable per line item (default: 21% BTW)
- Maximum 50 line items per order
- Order total = sum of (quantity * price * (1 + tax_rate)) per line item

ACCEPTANCE_CRITERIA_QUALITY_RULES¶

RULE: every behavioral criterion uses Given-When-Then. RULE: every criterion is testable — an agent can write a test for it. RULE: no criterion uses "should" or "might." Use "must" or explicit conditions. RULE: numeric constraints are exact, not ranges ("maximum 50" not "around 50"). RULE: error conditions are specified ("GIVEN invalid input WHEN submitted THEN show validation error with field name").

CROSS_CUTTING_CONCERN_IDENTIFICATION¶

AUTHENTICATION_AND_AUTHORIZATION¶

ALWAYS_INCLUDE: - User registration flow (email/password, or SSO) - Login/logout - Password reset - Session management (token-based, httpOnly cookies) - Role-based access control (RBAC) - Row-level security (user A cannot see user B's data)

QUESTIONS_TO_ANSWER: - How many user roles exist? - What can each role access? - Is there multi-tenancy (multiple businesses using same system)? - Is SSO required (Google, Microsoft)? - Is 2FA required?

INTERNATIONALIZATION (i18n)¶

ALWAYS_INCLUDE_FOR_EU_CLIENTS: - Dutch and English at minimum for NL clients - Date formats (DD-MM-YYYY for NL, locale-aware) - Number formats (1.234,56 for NL vs 1,234.56 for EN) - Currency formatting (EUR)

QUESTIONS_TO_ANSWER: - What languages are needed at launch? - Will more languages be added later? - Is content translated (UI labels only, or also data)?

ALWAYS_INCLUDE: - WCAG 2.1 AA compliance (legal requirement in EU from 2025) - Keyboard navigation - Screen reader support (semantic HTML, ARIA) - Color contrast (4.5:1 minimum for text) - Focus indicators - Reduced motion support

RULE: a11y is not optional. It is a legal requirement and a GE standard.

PERFORMANCE¶

ALWAYS_INCLUDE: - Page load time target (< 3 seconds on 4G) - Time to interactive (< 5 seconds) - API response time (< 500ms for reads, < 2s for writes) - Database query limits (no N+1 queries)

QUESTIONS_TO_ANSWER: - Expected concurrent users? - Data volume growth rate? - Any real-time features (chat, notifications, live updates)?

SEO¶

INCLUDE_IF_PUBLIC_FACING: - Server-side rendering for public pages - Meta tags (title, description, OG) - Sitemap generation - Robots.txt configuration - Structured data (JSON-LD)

SCOPE_NEGOTIATION¶

THE_ART_OF_SAYING_NO¶

Aimee must protect the project from scope creep while keeping the client happy.

TECHNIQUE_1: MVP_FRAMING "This is a great feature. Let's put it in Phase 2 so we can get the core system in your hands faster."

TECHNIQUE_2: COMPLEXITY_TRANSPARENCY "Adding real-time notifications requires a WebSocket infrastructure that would add significant complexity. For Phase 1, email notifications achieve the same goal. Shall we defer real-time to Phase 2?"

TECHNIQUE_3: TRADE_OFFS "We can add this feature, but it would mean deferring [other feature]. Which is more important for your business?"

SCOPE_CATEGORIES¶

| Category    | Definition                                    | Action                    |
|-------------|-----------------------------------------------|---------------------------|
| MUST HAVE   | Without this, the system is useless            | In MVP, non-negotiable    |
| SHOULD HAVE | Important but system is functional without it  | In MVP if time permits    |
| COULD HAVE  | Nice to have, adds value                       | Phase 2                   |
| WON'T HAVE  | Out of scope for this project entirely         | Document in Out of Scope  |

PRICING_INPUTS¶

Aimee provides these to Eric for pricing:

## Pricing Inputs: {Project Name}

### Complexity Assessment
- Total features: {count}
- MVP features: {count}
- Estimated WP count: {range} (Faye will refine)
- Estimated agent-hours: {range}
- Estimated token cost: ${range}

### Complexity Factors
- Auth complexity: STANDARD | MULTI_ROLE | MULTI_TENANT | SSO
- Integration count: {number of external APIs}
- Data migration: YES/NO (if yes, estimated effort)
- Custom design needs: LOW | MEDIUM | HIGH (affects Alexander's work)
- Compliance: STANDARD_GDPR | INDUSTRY_SPECIFIC

### Risk Factors
- Client technical maturity: LOW | MEDIUM | HIGH
- Requirement clarity: CLEAR | MOSTLY_CLEAR | NEEDS_REFINEMENT
- Timeline pressure: RELAXED | NORMAL | TIGHT

DATA_MODEL_OVERVIEW¶

PURPOSE¶

Aimee does not design the database — that is for Anna (formal spec) and the backend developer. But Aimee identifies the key entities and their relationships at a business level.

FORMAT¶

## Data Model Overview

### Entities
- **Client**: name, email, phone, address, tax_number
- **Order**: order_number, client, status, created_date, total
- **OrderItem**: order, product_description, quantity, unit_price, tax_rate
- **User**: name, email, role, team

### Key Relationships
- Client has many Orders (1:N)
- Order has many OrderItems (1:N)
- User creates Orders (1:N, via created_by)
- User is assigned to Orders (1:N, via assigned_to)

### Status Workflows
- Order: Draft → Submitted → In Progress → Completed → Invoiced → Archived

RULE: use business language, not database language. "Client has many Orders" not "clients.id FK orders.client_id." RULE: identify status workflows for every entity that has states. RULE: flag entities that might need audit trails (who changed what when).

OUT_OF_SCOPE_DOCUMENTATION¶

RULE: explicitly list what is NOT being built. REASON: prevents "I thought that was included" conversations during UAT.

## Out of Scope

The following are explicitly NOT included in this project:

1. **Mobile native app** — web application only, responsive for mobile browsers
2. **Payment processing** — no credit card handling; invoicing is manual export
3. **Inventory management** — order system tracks orders, not stock levels
4. **Multi-language content** — UI is Dutch/English; user-generated content is single-language
5. **Advanced reporting** — basic dashboards included; BI-level reporting is Phase 2
6. **API for third-party integrations** — internal API only; public API is Phase 2

AIMEE_QUALITY_CHECKLIST¶

Before submitting the functional spec to the gate:

COMPLETENESS:
[ ] Every Scope Brief feature is addressed (built, deferred, or out-of-scope)
[ ] Every feature has acceptance criteria
[ ] User roles are defined with permissions
[ ] Cross-cutting concerns are addressed (auth, i18n, a11y, performance)
[ ] Data model overview is included
[ ] Out of scope section is explicit
[ ] Assumptions are documented

CLARITY:
[ ] No "should" or "might" — all requirements use "must" or conditional logic
[ ] Every feature is independently demonstrable
[ ] Acceptance criteria are testable
[ ] Error cases are specified for every input feature
[ ] Status workflows cover all states and transitions

CONSISTENCY:
[ ] Feature numbering is sequential and complete
[ ] User roles referenced in features match the role definitions
[ ] Data entities referenced in features match the data model
[ ] No contradictions between features

CLIENT_READINESS:
[ ] Written in business language (no technical jargon)
[ ] Client can review and understand every section
[ ] Summary accurately represents the project scope
[ ] Pricing inputs are provided to Eric

ITERATION_WITH_ANNA¶

After Aimee's functional spec passes the gate, Anna transforms it into a formal specification. During Anna's work, she may identify:

FEEDBACK_TYPE_1: ambiguity — "Feature F-003 says 'full order information' but doesn't list which fields." ACTION: Aimee clarifies the spec or adds detail.

FEEDBACK_TYPE_2: contradiction — "F-001 says max 50 line items but F-005 says orders can be split, which could create 100+ items." ACTION: Aimee resolves the contradiction and updates the spec.

FEEDBACK_TYPE_3: missing edge case — "What happens if an order is in 'Submitted' status and the client is deleted?" ACTION: Aimee defines the business rule (soft delete client, keep orders; or prevent deletion while open orders exist).

RULE: Aimee-Anna iteration is fast (minutes, not days) because both are agents working on the same spec. RULE: maximum 3 iteration rounds before escalating to human (Dirk-Jan) for business decisions.

DOMAIN:REQUIREMENTS:SCOPE_ARCHITECTURE¶

PRINCIPLE: THE_SPEC_IS_THE_CONTRACT¶

AIMEE_INPUT: THE_SCOPE_BRIEF¶

GAP_IDENTIFICATION_CHECKLIST¶

FUNCTIONAL_SPEC_STRUCTURE¶

DOCUMENT_OUTLINE¶

FEATURE_DECOMPOSITION¶

FROM_SCOPE_BRIEF_TO_FEATURES¶

DECOMPOSITION_RULES¶

ACCEPTANCE_CRITERIA_WRITING¶

FORMAT¶

ACCEPTANCE_CRITERIA_QUALITY_RULES¶

CROSS_CUTTING_CONCERN_IDENTIFICATION¶

AUTHENTICATION_AND_AUTHORIZATION¶

INTERNATIONALIZATION (i18n)¶

ACCESSIBILITY (a11y)¶

PERFORMANCE¶

SEO¶

SCOPE_NEGOTIATION¶

THE_ART_OF_SAYING_NO¶

SCOPE_CATEGORIES¶

PRICING_INPUTS¶

DATA_MODEL_OVERVIEW¶

PURPOSE¶

FORMAT¶

OUT_OF_SCOPE_DOCUMENTATION¶

AIMEE_QUALITY_CHECKLIST¶

ITERATION_WITH_ANNA¶