ai-flow-dev 2.1.2 → 2.1.4

package/prompts/backend/flow-docs-sync.md

@@ -3,28 +3,24 @@
 **YOU ARE AN EXPERT TECHNICAL ARCHITECT AND DOCUMENTATION SPECIALIST.**
 
 Your mission is to detect changes in the codebase and update the project documentation automatically when the user executes `/flow-docs-sync`.
-
----
-
+---
 ## Command: `/flow-docs-sync`
 
 ### Objective
 
-Detect changes in the codebase compared to the last documented state (stored in `.ai-flow/analysis.json`) and update all affected documentation files automatically.
-
----
-
+Detect changes in the codebase compared to the last documented state (stored in `.ai-flow/cache/docs-analysis.json`) and update all affected documentation files automatically.
+---
 ## Execution Flow
 
 ### Step 1: Check for Analysis File
 
 ```
-First, check if `.ai-flow/analysis.json` exists:
+First, check if `.ai-flow/cache/docs-analysis.json` exists:
 
 - ✅ If exists → Proceed to Step 2 (Compare Changes)
 - ❌ If NOT exists → Execute full Phase 0 analysis first:
   - Run complete code analysis (as described in Phase 0)
-  - Create `.ai-flow/analysis.json` with current state
+  - Create `.ai-flow/cache/docs-analysis.json` with current state
   - Then proceed to Step 2
 ```
 
@@ -33,7 +29,6 @@ First, check if `.ai-flow/analysis.json` exists:
 **Reuse Phase 0 Analysis Logic:**
 
 1. **Perform Current Code Analysis:**
-
    - Execute the same analysis as Phase 0 (section 0.1):
      - File structure analysis
      - AST-based code parsing (endpoints, entities, dependencies)
@@ -42,8 +37,7 @@ First, check if `.ai-flow/analysis.json` exists:
    - Generate current state snapshot
 
 2. **Compare with Previous State:**
-
-   - Load `.ai-flow/analysis.json`
+   - Load `.ai-flow/cache/docs-analysis.json`
    - Compare current state vs previous state
    - Detect changes in:
      - **Endpoints:** New, modified, or deleted endpoints
@@ -84,185 +78,32 @@ First, check if `.ai-flow/analysis.json` exists:
 
 No se requiere ninguna actualización.
 ```
-
----
-
+---
 ## 📊 MERMAID DIAGRAM REGENERATION GUIDELINES
 
-When regenerating or updating diagrams in documentation files, follow these **critical** formatting rules:
+> 📎 **Reference:** See [prompts/shared/mermaid-guidelines.md](../shared/mermaid-guidelines.md) for all Mermaid diagram formatting rules (ER, Architecture, Flow).
 
 ### ER Diagrams (data-model.md)
 
-**Diagram Type:** `erDiagram`
-
-**Requirements:**
-1. Show ALL entities and their relationships
-2. Include field types and constraints (PK, FK, UK)
-3. Add descriptions for complex or business-critical fields
-4. Verify relationship cardinality matches actual database schema
-5. Keep entity order logical (core entities first, then related)
-
-**Quality Checklist:**
-- [ ] Code fence is exactly ` ```mermaid ` (lowercase, no spaces)
-- [ ] All entities from database are represented
-- [ ] All foreign key relationships are shown
-- [ ] Primary keys are marked with `PK`
-- [ ] Foreign keys are marked with `FK`
-- [ ] Many-to-many relationships use junction tables
-- [ ] Field types match database schema
-- [ ] Diagram renders without errors
-
-**Example:**
-````markdown
-```mermaid
-erDiagram
-    USER ||--o{ ORDER : places
-    PRODUCT ||--o{ ORDER_ITEM : contains
-    ORDER ||--o{ ORDER_ITEM : includes
-
-    USER {
-        string id PK
-        string email UK
-        string name
-        datetime createdAt
-    }
-
-    ORDER {
-        string id PK
-        string userId FK
-        decimal total
-        string status
-    }
-
-    PRODUCT {
-        string id PK
-        string name
-        decimal price
-    }
-
-    ORDER_ITEM {
-        string id PK
-        string orderId FK
-        string productId FK
-        int quantity
-    }
-```
-````
-
----
-
+> 📎 **Reference:** See [prompts/shared/mermaid-guidelines.md](../shared/mermaid-guidelines.md) for ER diagram syntax, relationship notation, and common mistakes.
+---
 ### Architecture Diagrams (architecture.md)
 
-**Diagram Type:** `graph TD` (or `graph LR`)
-
-**Requirements:**
-1. Show ALL major system components (services, databases, caches, queues)
-2. Label connections with protocols/methods (HTTPS, gRPC, REST, etc.)
-3. Use consistent styling (databases as cylinders, services as boxes)
-4. Include external integrations (Email, Payment, SMS services)
-5. Show monitoring and logging components if present
-6. Include deployment context (load balancers, CDN) if relevant
-
-**Quality Checklist:**
-- [ ] Code fence is exactly ` ```mermaid ` (lowercase, no spaces)
-- [ ] All services/components from codebase are shown
-- [ ] Database connections are labeled
-- [ ] External APIs are included
-- [ ] Authentication/authorization flow is visible
-- [ ] Caching layer is shown (if exists)
-- [ ] Message queues are included (if exists)
-- [ ] Styling is applied for clarity
-- [ ] Diagram renders without errors
-
-**Example:**
-````markdown
-```mermaid
-graph TD
-    Client[Client Application]
-    API[API Gateway<br/>Express/NestJS]
-    Auth[Auth Service<br/>JWT]
-    DB[(PostgreSQL)]
-    Cache[(Redis)]
-    Queue[Message Queue<br/>RabbitMQ]
-
-    Client -->|HTTPS| API
-    API -->|Verify| Auth
-    API -->|Query| DB
-    API -->|Cache| Cache
-    API -->|Enqueue| Queue
-
-    style DB fill:#e1ffe1
-    style Cache fill:#f0e1ff
-```
-````
-
----
-
+> 📎 **Reference:** See [prompts/shared/mermaid-guidelines.md](../shared/mermaid-guidelines.md) for architecture diagram syntax, node shapes, and styling.
+---
+---
 ### Business Flow Diagrams (project-brief.md)
 
-**Diagram Type:** `flowchart TD` (or `flowchart LR`)
-
-**Requirements:**
-1. Start with `([Start Terminal])`
-2. End with `([End Terminal])`
-3. Use `{Diamond}` for ALL decision points
-4. Label ALL decision branches clearly (`-->|Yes|`, `-->|No|`)
-5. Show complete paths (including error/failure scenarios)
-6. Keep flows readable (avoid crossing arrows when possible)
-7. Use consistent styling for node types
-
-**Quality Checklist:**
-- [ ] Code fence is exactly ` ```mermaid ` (lowercase, no spaces)
-- [ ] Flow starts with a terminal node
-- [ ] Flow ends with terminal node(s)
-- [ ] All decision points have labeled branches
-- [ ] All paths lead to an end state
-- [ ] Error/failure paths are included
-- [ ] Node labels are clear and concise
-- [ ] Line breaks (`<br/>`) used for readability
-- [ ] Styling applied for visual clarity
-- [ ] Diagram renders without errors
-
-**Example:**
-````markdown
-```mermaid
-flowchart TD
-    Start([User Starts Process]) --> Action1[Perform Action]
-    Action1 --> Decision{Success?}
-
-    Decision -->|Yes| Success[Process Complete]
-    Decision -->|No| Retry{Retry?}
-
-    Retry -->|Yes| Action1
-    Retry -->|No| Failed[Process Failed]
-
-    Success --> End1([End: Success])
-    Failed --> End2([End: Failed])
-
-    style Start fill:#e1f5ff
-    style End1 fill:#e1ffe1
-    style End2 fill:#ffe1e1
-```
-````
-
----
-
+> 📎 **Reference:** See [prompts/shared/mermaid-guidelines.md](../shared/mermaid-guidelines.md) for business flow syntax, decision points, and styling.
+---
 ### Common Formatting Rules (ALL Diagrams)
 
-**CRITICAL - Code Fence Syntax:**
-```
-✅ CORRECT: ```mermaid
-❌ WRONG:   ```Mermaid (capital M)
-❌ WRONG:   ``` mermaid (extra space)
-❌ WRONG:   ``mermaid (missing backtick)
-```
-
-**Indentation:**
-- Start Mermaid syntax at column 0 (no leading spaces/tabs)
-- Only indent within Mermaid syntax according to Mermaid rules
+> 📎 **Reference:** See [prompts/shared/mermaid-guidelines.md](../shared/mermaid-guidelines.md) for critical code fence syntax and indentation rules.
+---
 - Do NOT indent the entire code block
 
 **Validation Steps:**
+
 1. After generating/updating diagram, verify syntax at https://mermaid.live/
 2. Check that diagram renders in VS Code markdown preview
 3. Verify all nodes and relationships are present
@@ -270,15 +111,14 @@ flowchart TD
 5. Test that styling is applied correctly
 
 **When Updating Existing Diagrams:**
+
 1. Read the current diagram first
 2. Identify what needs to be added/removed/modified
 3. Maintain existing styling and layout patterns
 4. Add new elements in logical positions
 5. Preserve comments or notes if present
 6. Verify the entire diagram still renders after changes
-
----
-
+---
 ### Step 4: Update Documents (If User Confirms)
 
 **If user responds "Y", "Yes", "y", "yes", or similar:**
@@ -286,7 +126,6 @@ flowchart TD
 1. **For each document that needs updating:**
 
    **A) `docs/api.md`** (if endpoints changed):
-
    - Read current `docs/api.md`
    - Identify new/modified endpoints from analysis
    - Add new endpoints following existing API conventions
@@ -296,7 +135,6 @@ flowchart TD
    - Regenerate affected sections only
 
    **B) `docs/data-model.md`** (if entities changed):
-
    - Read current `docs/data-model.md`
    - Update entity definitions with new fields
    - Update relationships if changed
@@ -304,41 +142,35 @@ flowchart TD
    - Maintain all existing content that hasn't changed
 
    **C) `ai-instructions.md`** (if dependencies changed):
-
    - Read current `ai-instructions.md`
    - Add new dependencies to appropriate sections
    - Update version numbers if changed
    - Maintain all existing rules and patterns
 
    **D) `docs/architecture.md`** (if architecture changed):
-
    - Read current `docs/architecture.md`
    - Update architecture diagram (mermaid) if structure changed
    - Update module descriptions
    - Maintain all existing content
 
    **E) `specs/configuration.md`** (if env vars changed):
-
    - Read current `specs/configuration.md`
    - Add new environment variables
    - Update descriptions if changed
    - Maintain existing variables
 
    **F) `.env.example`** (if env vars changed):
-
    - Read current `.env.example`
    - Add new environment variables with example values
    - Maintain existing variables
 
    **G) `specs/security.md`** (if security patterns changed):
-
    - Read current `specs/security.md`
    - Update security policies if authentication/authorization changed
    - Maintain existing policies
 
-2. **Update `analysis.json`:**
-
-   - Save current state to `.ai-flow/analysis.json`
+2. **Update `docs-analysis.json`:**
+   - Save current state to `.ai-flow/cache/docs-analysis.json`
    - Update timestamp
    - Include all detected changes in metadata
 
@@ -359,7 +191,7 @@ flowchart TD
 - Agregada dependencia "@nestjs/swagger"
 - Actualizada sección de herramientas
 
-✅ analysis.json actualizado con nuevo estado
+✅ docs-analysis.json actualizado con nuevo estado
 ```
 
 ### Step 5: Handle Cancellation
@@ -369,9 +201,7 @@ flowchart TD
 ```
 Actualización cancelada. Ejecuta `/flow-docs-sync` cuando estés listo para actualizar la documentación.
 ```
-
----
-
+---
 ## Change Detection Rules
 
 ### Endpoints Detection
@@ -450,42 +280,34 @@ Actualización cancelada. Ejecuta `/flow-docs-sync` cuando estés listo para act
 - Add new variables to configuration spec
 - Add examples to `.env.example`
 - Maintain existing variables
-
----
-
+---
 ## Important Rules
 
 1. **Incremental Updates Only:**
-
    - Only modify sections that changed
    - Preserve all existing content that hasn't changed
    - Maintain document structure and formatting
 
 2. **Follow Existing Patterns:**
-
    - Use same format as existing documentation
    - Follow conventions established in original build
    - Maintain consistency with existing docs
 
 3. **Update Analysis File:**
-
-   - Always update `.ai-flow/analysis.json` after document updates
+   - Always update `.ai-flow/cache/docs-analysis.json` after document updates
    - Include timestamp and change summary
    - Save complete current state for next comparison
 
 4. **Mermaid Diagrams:**
-
    - Regenerate ER diagrams when entities change
    - Regenerate architecture diagrams when structure changes
    - Use mermaid format for all diagrams
 
 5. **Error Handling:**
    - If document doesn't exist, create it following template
-   - If analysis.json is corrupted, regenerate it
+   - If docs-analysis.json is corrupted, regenerate it
    - If comparison fails, show error and suggest full Phase 0 re-run
-
----
-
+---
 ## Example Execution
 
 ```
@@ -515,13 +337,12 @@ AI:
 - Agregado campo "avatarUrl" (String, nullable) a entidad User
 - Actualizado diagrama ER (mermaid) con nuevo campo
 
-✅ analysis.json actualizado con nuevo estado
+✅ docs-analysis.json actualizado con nuevo estado
 
 Documentación sincronizada exitosamente.
 ```
-
----
-
+---
 **BEGIN EXECUTION when user runs `/flow-docs-sync`**
 
 
+