Lokstra Module Requirements

Lokstra Module Requirements Generation

When to use this skill

Use this skill when:

• BRD has been published with approval in docs/modules/{project}/BRD-*.md
• Need to identify bounded contexts (modules) from business requirements
• Breaking down business requirements into technical modules
• Defining module dependencies and interfaces
• Creating detailed functional requirements per module

Prerequisites Check (CRITICAL)

Before proceeding, verify:

1. Published BRD exists: docs/modules/{project}/BRD-{project}-v*.md (not drafts/)
2. BRD has approval section with sign-offs

If missing: Stop, use lokstra-brd-generation first, get approval, publish to docs/modules/

How to generate module requirements

Step 1: Identify Modules (Bounded Contexts)

Interactive Mode (Default):

Agent analyzes approved BRD and proposes modules:

Based on the approved BRD, I identify these modules:

1. auth - Authentication & authorization (handles FR-001 to FR-005)
2. user-profile - User information management (FR-006 to FR-010)
3. product - Product catalog (FR-011 to FR-020)
4. order - Order management (FR-021 to FR-030)
5. payment - Payment processing (FR-031 to FR-035)
6. notification - Email/SMS notifications (FR-036 to FR-040)

Do you agree with this breakdown? Would you like to:
- Approve as-is
- Merge some modules (e.g., auth + user-profile)
- Split modules further (e.g., separate inventory from product)
- Add/remove modules

Proposal Mode (If developer requests):

Developer can ask agent to propose alternative module structures:

Developer: "Can you propose a microservices architecture?"
Developer: "What if we combine auth and user-profile?"
Developer: "Show me a modular monolith structure"

Agent provides reasoning for each proposal.

Guiding Questions:

• "Could this be a separate microservice?"
• "Does this have its own domain logic?"
• "Can this scale independently?"

Example: auth, user-profile, product, order, payment, notification

Anti-pattern: One big user module for auth + profile + notifications (combine when truly related only)

Step 2: For Each Module, Generate Requirements

Draft Phase: Save to: docs/drafts/{module}/REQUIREMENTS-{module}-v{version}-draft.md

Published Phase: Save to: docs/modules/{module}/REQUIREMENTS-{module}-v{version}.md

Versioning: Same as BRD (v1.0-draft → v1.1-draft → v1.1 published)

Use template from references/MODULE_REQUIREMENTS_TEMPLATE.md

Required Sections:

1. Module Overview - Bounded context & dependencies only
2. Functional Requirements - FR-{MODULE}-001, FR-{MODULE}-002, etc.
3. Domain Model - Entities, value objects
4. Use Cases - Step-by-step flows
5. Data Validation Rules
6. Error Handling
7. Security Requirements
8. Performance Requirements
9. Integration Points - Dependencies on other modules

Step 3: Document Integration Points

Integration Points describe WHAT dependencies exist (business perspective).

Actual implementation (HOW to inject via @Inject) is handled during code generation phase.

Rules:

• No circular dependencies
• Shared domain models in /modules/shared/domain/
• All cross-module communication documented in "Integration Points" section

In Requirements Document: List which modules this one depends on and why, under "9. Integration Points" section (not YAML config)

Module Requirements Format

# Module Requirements: [Module Name]
## [Project Name]

**Version:** 1.0.0  
**Status:** draft  
**BRD Reference:** BRD v1.0.0  
**Last Updated:** 2026-01-28  
**Module Owner:** [Name/Team]

---

## 1. Module Overview

**Module Name:** [Module Name]  
**Purpose:** [One sentence what this module does]

**Bounded Context:**
- What domain concepts this module owns
- What it does NOT own (belongs to other modules)

**Dependencies:**
- List which modules this one depends on (e.g., "Needs auth module for user verification")
- Document the business/functional reason, not technical implementation

**Dependent Modules:**
- List which modules depend on this one (informational)

---

## 2. Functional Requirements

### FR-[MODULE]-001: [Requirement Name]
**BRD Reference:** FR-XXX  
**Priority:** High/Medium/Low  
**User Story:** As a [role], I want to [action] so that [benefit].

**Acceptance Criteria:**
- [Criterion 1]
- [Criterion 2]

**Business Rules:**
- [Rule 1]
- [Rule 2]

**API Endpoint:**
- Method: POST
- Path: `/api/[resource]`
- Authentication: Required
- Authorization: [Roles]

---

## 3. Domain Model

### Entities

#### [Entity Name]
**Attributes:**
- `id`: UUID - Unique identifier
- `[field]`: [Type] - [Description]
- `created_at`: Timestamp
- `updated_at`: Timestamp

**Relationships:**
- Belongs to: [Entity]
- Has many: [Entity]

**Business Rules:**
- [Rule 1]

---

## 4. Use Cases

### UC-[MODULE]-001: [Use Case Name]
**Actor:** [User role]  
**Goal:** [What actor wants]

**Preconditions:**
- [Condition 1]

**Main Flow:**
1. [Step 1]
2. [Step 2]
3. [Step 3]

**Alternative Flows:**
- [Alt flow]

**Postconditions:**
- [Result]

---

## 5. Validation Rules

| Field | Rules | Error Message |
|-------|-------|---------------|
| name  | Required, Min 3, Max 50 | "Name must be 3-50 characters" |
| email | Required, Email format | "Invalid email format" |

---

## 6. Error Handling

| Code | HTTP Status | Description | User Message |
|------|-------------|-------------|--------------|
| [MODULE]_001 | 400 | [Error] | "[Message]" |

---

## 7. Security Requirements

**Authentication:** JWT tokens  
**Authorization:**
- Endpoint 1: [Roles]
- Endpoint 2: [Roles]

**Data Protection:**
- [What data needs encryption]

---

## 8. Performance Requirements

- List operations: < 100ms (p95)
- Create operations: < 200ms (p95)
- Database queries: < 50ms (p99)

---

## 9. Integration Points

### Dependencies
| Module | Purpose | Data Exchanged |
|--------|---------|----------------|
| auth | Verify tokens | User ID, roles |

### Provides To
| Module | Purpose | Data Exchanged |
|--------|---------|----------------|
| order | Product details | Product info |

---

## Technical Implementation Note

**Dependency Injection:** When you proceed to code generation:
- Document "Integration Points" in requirements
- Technical implementation via `@Inject` is handled in `lokstra-code-implementation` skill
- Agent will create proper service dependencies based on integration points documented here

Validation Checklist

Before proceeding to API specification:

• All modules identified with clear boundaries
• No circular dependencies (use dependency diagram to verify)
• Each FR has acceptance criteria
• Domain entities defined with tenant_id (multi-tenant)
• Use cases documented
• Validation rules specified
• Performance requirements measurable
• Multi-tenant isolation strategy documented
• Module owner assigned

See references/VALIDATION_CHECKLIST.md for comprehensive 12-section validation.

Common Mistakes to Avoid

Review references/ANTI_PATTERNS.md for 14 common anti-patterns:

• God Module (one module does everything)
• Circular dependencies
• Leaky tenant isolation (missing tenant_id filters)
• Vague requirements ("should be fast")
• Missing bounded context
• No multi-tenant strategy (adding later = expensive)
• Ignoring NFRs, integration points, validation, errors

Next Steps

After module requirements approved:

1. Use lokstra-api-specification skill for each module
2. Use lokstra-schema-design skill for database design
3. Then proceed to code generation

Reference Files

For Getting Started:

• MODULE_REQUIREMENTS_TEMPLATE.md - Comprehensive 16-section template (Overview, FRs, Domain Model, Use Cases, Validation, Security, Performance, Integration, Multi-Tenant, Testing, etc.)

For Examples & Diagrams:

• AUTH_MODULE_EXAMPLE.md - Real-world multi-tenant authentication module with RBAC, tenant isolation, JWT, and all sections completed
• MODULE_DEPENDENCY_DIAGRAMS.md - 8 Mermaid diagram templates (Dependency Graph, Tenant Context Flow, Architecture Layers, Interaction, Bounded Context Map, Circular Detection, Maturity Levels, Isolation Strategy)

For Quality & Validation:

• VALIDATION_CHECKLIST.md - 12-section comprehensive checklist with 100+ validation points, quality scoring, common failures, and multi-tenant specific checks
• ANTI_PATTERNS.md - 14 common mistakes with examples and solutions (God Module, Circular Dependencies, Leaky Isolation, Vague Requirements, etc.)

Converted and distributed by TomeVault — claim your Tome and manage your conversions.