eva4j 1.0.17 → 1.0.18

package/src/skills/requirements-elicitation/references/output-templates.md

@@ -0,0 +1,368 @@
+# Output Templates — Requirements Elicitation
+
+Templates exactos para los tres artefactos generados en la Fase 4. Todo contenido en inglés.
+
+---
+
+## Template 1: FUNCTIONAL_REQUIREMENTS.md
+
+```markdown
+# Functional Requirements — [Product Name]
+
+> Generated by requirements-elicitation skill. Intended as input for build-system-yaml.
+> Last updated: [date]
+
+---
+
+## Product Overview
+
+**Problem Statement:** [1–2 sentences describing the core problem this product solves]
+
+**Target Users:** [Who this is built for, in business terms]
+
+**Core Value Proposition:** [The "aha moment" — what the user gains from using this system]
+
+---
+
+## Actors
+
+| Actor | Description | Primary Actions |
+|-------|-------------|-----------------|
+| [Actor1] | [Role description] | [Comma-separated key actions] |
+| [Actor2] | [Role description] | [Comma-separated key actions] |
+| [System/Cron] | [If applicable] | [Automated actions] |
+
+---
+
+## Modules (Bounded Contexts)
+
+> These are the suggested bounded contexts derived from the functional requirements.
+> The build-system-yaml skill will use these as starting points for module design.
+
+| Module | Responsibility | Key Entities |
+|--------|---------------|--------------|
+| [module-name] | [One-line responsibility] | [Entity1, Entity2] |
+| [module-name] | [One-line responsibility] | [Entity1, Entity2] |
+
+---
+
+## Use Cases
+
+### UC-001 — [Use Case Name]
+
+**Actor:** [Who performs this action]  
+**Module:** [Which module handles this]  
+**Trigger:** [What initiates this use case]
+
+**Preconditions:**
+- [Condition that must be true before this can happen]
+- [Another precondition]
+
+**Main Flow:**
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+...
+
+**Postconditions:**
+- [What is true after this succeeds]
+- [Side effects: notifications sent, states changed, records created]
+
+**Business Rules Applied:**
+- BR-001: [Reference to validation rule]
+- BR-005: [Reference to another rule]
+
+**Alternative Flows:**
+- [Condition] → [What happens instead]
+- [Error condition] → [Error handling]
+
+---
+
+### UC-002 — [Use Case Name]
+
+[Same structure as above]
+
+---
+
+## Entity Lifecycles
+
+### [EntityName] State Machine
+
+```
+[INITIAL_STATE] --(create: Actor)--> [STATE_A]
+[STATE_A] --(action: Actor / condition)--> [STATE_B]
+[STATE_A] --(cancel: Actor)--> [CANCELLED]
+[STATE_B] --(complete: Actor/System)--> [COMPLETED]
+[CANCELLED] — terminal state, no further transitions
+[COMPLETED] — terminal state, no further transitions
+```
+
+**State descriptions:**
+- `INITIAL_STATE` — [What this state means in business terms]
+- `STATE_A` — [Business meaning]
+- `STATE_B` — [Business meaning]
+- `CANCELLED` — [Under what conditions an entity reaches this state]
+- `COMPLETED` — [What completion means for this entity]
+
+---
+
+## External Integrations
+
+| System | Type | Purpose | Failure Behavior |
+|--------|------|---------|-----------------|
+| [Payment Gateway] | Sync HTTP | Process payments | Retry 3x, then mark order as payment_failed |
+| [Email Service] | Async | Send notifications | Queue for retry, non-blocking |
+| [ERP System] | Async | Sync inventory | Log failure, alert ops team |
+
+---
+
+## Non-Functional Requirements (Business-Defined)
+
+- **Availability:** [e.g., "The checkout process must be available 99.9% of the time"]
+- **Data Retention:** [e.g., "Order history must be kept for 7 years"]
+- **Audit:** [e.g., "All status changes must be logged with who and when"]
+- **Notifications:** [e.g., "Customers must receive email within 5 minutes of order placement"]
+- **Concurrency:** [e.g., "Stock reservation must be atomic — two simultaneous purchases cannot both succeed for the last item"]
+```
+
+---
+
+## Template 2: PRODUCT_FLOWS.md
+
+```markdown
+# Product Flows — [Product Name]
+
+> Captures step-by-step interactions between actors and the system.
+> Includes happy paths, alternative flows, and edge cases per actor.
+
+---
+
+## Actor: [Actor1 Name]
+
+### Flow 1 — [Main Flow Name]
+
+**Goal:** [What the actor is trying to achieve]  
+**Entry Point:** [Where/how the flow starts]  
+**Success Outcome:** [What success looks like for this actor]
+
+```
+Step 1: [Actor] [verb] [object]
+  → System [response/validation]
+  
+Step 2: [Actor] [verb] [object]
+  → System [response/validation]
+  → System triggers: [background action, notification, state change]
+
+Step 3: ...
+
+✅ Success: [Final state / confirmation to user]
+```
+
+**Alternative Path — [Condition]:**
+```
+At Step [N]: [Condition occurs]
+  → System: [Response]
+  → [Actor]: [Options presented]
+  → Flow continues at Step [M] / Flow ends with [outcome]
+```
+
+**Error Path — [Error Condition]:**
+```
+At Step [N]: [Error condition]
+  → System: [Error message / recovery action]
+  → [Actor]: [What they see / can do]
+```
+
+---
+
+### Flow 2 — [Another Flow for same actor]
+
+[Same structure]
+
+---
+
+## Actor: [Actor2 Name]
+
+### Flow 1 — [Flow Name]
+
+[Same structure]
+
+---
+
+## System-Initiated Flows (Automated)
+
+### Auto-Flow 1 — [Flow Name]
+
+**Trigger:** [What event or schedule initiates this]  
+**Actors notified:** [Who receives output of this flow]
+
+```
+Trigger: [Event / schedule]
+  → System: [Action 1]
+  → System: [Action 2]
+  → Notification sent to: [Actor] via [channel]
+```
+
+---
+
+## Cross-Actor Flows (Multiple actors involved)
+
+### [Flow Name] — [Actor1] initiates, [Actor2] approves
+
+```
+[Actor1]:
+  Step 1: [Creates/submits something]
+  → System: [Saves, notifies Actor2]
+
+[Actor2]:
+  Step 2: Reviews [what was submitted]
+  → Decision: Approve / Reject
+
+  If Approve:
+    → System: [State change, notification to Actor1]
+  
+  If Reject:
+    → System: [State change, notification to Actor1 with reason]
+
+[Actor1]:
+  Step 3: [Receives notification, takes follow-up action if needed]
+```
+```
+
+---
+
+## Template 3: BUSINESS_RULES.md
+
+```markdown
+# Business Rules — [Product Name]
+
+> Defines all business invariants, validation rules, and constraint enforcement logic.
+> These rules are the source of truth for what the system must enforce.
+
+---
+
+## Business Rules Reference
+
+| ID | Rule | Context | Enforcement Point | Violation Response |
+|----|------|---------|-------------------|-------------------|
+| BR-001 | [Rule description] | [When it applies] | [Create / Update / Transition] | [Error message / behavior] |
+| BR-002 | [Rule description] | [When it applies] | [Create / Update / Transition] | [Error message / behavior] |
+| BR-003 | [Rule description] | [When it applies] | [Create / Update / Transition] | [Error message / behavior] |
+
+---
+
+## Validation Rules by Operation
+
+### [UseCase / Operation Name]
+
+**Input validations** (enforced before processing):
+
+| Field | Rule | Error if violated |
+|-------|------|-------------------|
+| [fieldName] | Must not be null | "Field X is required" |
+| [fieldName] | Must be positive | "Amount must be greater than 0" |
+| [fieldName] | Must match pattern | "Invalid format for field X" |
+
+**Business validations** (enforced after input parsing, against domain state):
+
+| Rule | Check | Error if violated |
+|------|-------|-------------------|
+| BR-001 | [What is checked] | "[Business error message]" |
+| BR-004 | [What is checked] | "[Business error message]" |
+
+**Post-conditions** (enforced after operation completes):
+- [State guaranteed to be true after success]
+- [Side effect guaranteed to occur]
+
+---
+
+### [Another UseCase]
+
+[Same structure]
+
+---
+
+## State Transition Guards
+
+For each transition in the entity lifecycle, define the guard conditions:
+
+### [EntityName] Transitions
+
+| From State | To State | Trigger | Guard Conditions | Violation Response |
+|-----------|---------|---------|-----------------|-------------------|
+| [STATE_A] | [STATE_B] | [method/action] | [Condition that must be true] | [Error] |
+| [STATE_A] | [CANCELLED] | cancel | Not in terminal state | "Cannot cancel a [state] [entity]" |
+| [STATE_B] | [COMPLETED] | complete | [Condition] | [Error] |
+
+---
+
+## Concurrency & Race Conditions
+
+| Scenario | Risk | Resolution Strategy |
+|---------|------|---------------------|
+| Two users buying the last item simultaneously | Oversell | Atomic stock reservation; first transaction wins, second gets "out of stock" error |
+| Two admins approving the same request | Double processing | Optimistic locking; second approval fails with "already processed" |
+| [Another scenario] | [Risk] | [How system handles it] |
+
+---
+
+## Time-Based Rules
+
+| Rule | Entity | Condition | Automatic Action |
+|------|--------|-----------|-----------------|
+| Order expires if unpaid | Order | 30 minutes after creation without payment | Status → EXPIRED; stock released |
+| Reservation reminder | Appointment | 24 hours before scheduled time | Email/SMS sent to customer |
+| [Other time rule] | [Entity] | [Condition] | [Action] |
+
+---
+
+## Cross-Module Validation Dependencies
+
+When a module needs to validate data from another module before proceeding:
+
+| Requesting Module | Data Needed From | Check | Failure Behavior |
+|-----------------|-----------------|-------|-----------------|
+| [orders] | [inventory] | Product exists and has stock | Return error "Product unavailable" |
+| [bookings] | [schedules] | Time slot is available | Return error "Slot already taken" |
+| [payments] | [orders] | Order is in correct state for payment | Return error "Order cannot be paid in current state" |
+
+---
+
+## Error Catalog
+
+| Code | Message | HTTP Status | When Raised |
+|------|---------|-------------|-------------|
+| [ENTITY]_NOT_FOUND | "[Entity] with id {id} not found" | 404 | Any operation on non-existent entity |
+| [ENTITY]_INVALID_STATE | "Cannot [action] a [state] [entity]" | 422 | State transition violation |
+| [ENTITY]_VALIDATION_ERROR | "[Specific validation message]" | 400 | Input or business rule violation |
+| INSUFFICIENT_[RESOURCE] | "[Resource] is insufficient for this operation" | 422 | Stock, balance, quota exceeded |
+| CONCURRENT_MODIFICATION | "[Entity] was modified by another operation" | 409 | Optimistic locking failure |
+```
+
+---
+
+## Notes on Using These Templates
+
+### What to fill vs. what to leave for build-system-yaml
+
+**Fill completely in this skill:**
+- All use case names and their flows
+- All business rules (with BR-XXX IDs)
+- All state machine transitions including guards
+- All external integrations and their failure behavior
+- All error messages and codes
+
+**Leave for build-system-yaml to decide:**
+- Exact entity field names and types
+- Whether to use Kafka, RabbitMQ, or HTTP for cross-module communication
+- Database schema details
+- API path structures (beyond what's in the flows)
+- Exact module splits (the skill will propose split based on the requirements)
+
+### Naming Conventions for Generated Files
+
+- Use case names: `PascalCase` (e.g., `ConfirmOrder`, `CancelBooking`)
+- Business rule IDs: `BR-NNN` (sequential, module-agnostic at this stage)
+- State names: `SCREAMING_SNAKE_CASE` (maps directly to Java enums)
+- Actor names: `PascalCase` (e.g., `Customer`, `Admin`, `DeliveryDriver`)
+- Module names in tables: `kebab-case` (e.g., `orders`, `inventory`, `notifications`)