​

Logic Validator

​

Purpose

1. All PRD features and stories are represented in diagrams
2. Entities and flows are consistent across different diagram types
3. Both happy paths and error scenarios are documented
4. Every diagram element traces back to a PRD requirement
5. Naming conventions are coherent across all artifacts
6. Feature dependencies are properly sequenced

​

Inputs

​

Outputs

{
  "overall_score": "number (0.0-1.0)",
  "status": "approved|rejected|pending",
  "breakdown": {
    "coverage": {
      "score": "number",
      "weight": 0.25,
      "details": "string"
    },
    "consistency": {
      "score": "number",
      "weight": 0.25,
      "details": "string"
    },
    "completeness": {
      "score": "number",
      "weight": 0.20,
      "details": "string"
    },
    "traceability": {
      "score": "number",
      "weight": 0.15,
      "details": "string"
    },
    "naming_coherence": {
      "score": "number",
      "weight": 0.10,
      "details": "string"
    },
    "dependency_integrity": {
      "score": "number",
      "weight": 0.05,
      "details": "string"
    }
  },
  "warnings": ["string"],
  "suggestions": ["string"],
  "timestamp": "ISO timestamp"
}

​

Validation Criteria

​

1. Coverage (Weight: 0.25)

coverage_score = (mapped_elements / total_elements)

• Is feature F001 visualized in any flowchart or sequence diagram?
• Is user story US015 traceable to a diagram node?
• Are all acceptance criteria represented visually?

• Missing user stories in sequence diagrams
• Features without visual representation
• Orphaned acceptance criteria

​

2. Consistency (Weight: 0.25)

consistency_score = 1.0 - (inconsistencies / total_cross_references)

• Does the User entity have the same attributes in ER and sequence diagrams?
• Are relationship cardinalities consistent (e.g., User-Order is 1:N everywhere)?
• Do flow states match state diagram definitions?

• Entity “Payment” has different attributes in ER vs sequence diagram
• Relationship “User has Cart” is 1:1 in ER but 1:N in flowchart
• State names differ between stateDiagram and flowchart nodes

​

3. Completeness (Weight: 0.20)

completeness_score = (paths_with_error_handling / total_paths)

• Does the checkout flow include payment failure scenarios?
• Are timeout and network error paths documented?
• Do state diagrams include rollback/cancel transitions?

• Missing “payment failed” branch in checkout flow
• No timeout handling in authentication sequence
• State diagram lacks “cancel order” transition

​

4. Traceability (Weight: 0.15)

traceability_score = (traceable_elements / total_diagram_elements)

• Can each flowchart node be linked to a PRD section?
• Are sequence diagram actors defined in personas?
• Do state transitions map to acceptance criteria?

• Flowchart node “Verify inventory” has no PRD requirement
• Sequence actor “Notification Service” not mentioned in PRD
• State transition undocumented in feature description

​

5. Naming Coherence (Weight: 0.10)

naming_score = 1.0 - (naming_conflicts / total_named_elements)

• Is it “User” or “Customer” or “Usuário”?
• Are acronyms used consistently (API vs Api)?
• Do entity names match between code and diagrams?

• Entity called “User” in ER but “Customer” in sequence diagram
• Mixing English/Portuguese terms (“Usuário” vs “User”)
• Inconsistent capitalization (“OrderItem” vs “Order_Item”)

​

6. Dependency Integrity (Weight: 0.05)

dependency_score = (valid_sequences / total_sequences)

• Is feature F002 only shown after F001 (its dependency)?
• Do flows respect prerequisite steps?
• Are dependent features properly linked in Gantt charts?

• Checkout flow appears before authentication (dependency)
• Feature F005 shown in timeline before F004 (its prerequisite)
• State transition assumes previous state not yet defined

​

Score Calculation Formula

overall_score = (coverage × 0.25) + 
                (consistency × 0.25) + 
                (completeness × 0.20) + 
                (traceability × 0.15) + 
                (naming_coherence × 0.10) + 
                (dependency_integrity × 0.05)

​

Validation Modes

​

Interactive Mode

validation_mode: interactive

1. Present diagram #1 with its individual score
2. Wait for user input: approve | reject | modify
3. If modify: collect feedback and return to Phase 2 (Mermaid Gen)
4. If approve: proceed to next diagram
5. If reject: mark diagram for regeneration
6. Repeat for all diagrams
7. Final decision: proceed to Figma if all approved

​

Batch Mode

validation_mode: batch

1. Present all diagrams together
2. Show consolidated validation report
3. Wait for user input: approve_all | reject_all | select
4. If select: user chooses which diagrams to approve/reject
5. Regenerate rejected diagrams with aggregated feedback
6. Single decision point for entire batch

​

Auto Mode

validation_mode: auto
validation_threshold: 0.85

1. Calculate overall_score
2. If overall_score >= threshold: status = “approved”, proceed to Phase 4 (Figma)
3. If overall_score < threshold: status = “rejected”, generate feedback report
4. Return to Phase 2 with specific improvement suggestions
5. No human intervention required

​

Example Validation Report

{
  "overall_score": 0.91,
  "status": "approved",
  "breakdown": {
    "coverage": {
      "score": 0.95,
      "weight": 0.25,
      "details": "19/20 features covered. Missing: F020 (Admin Dashboard)"
    },
    "consistency": {
      "score": 0.88,
      "weight": 0.25,
      "details": "Payment entity has 3 attribute mismatches between ER and sequence diagrams"
    },
    "completeness": {
      "score": 0.90,
      "weight": 0.20,
      "details": "18/20 flows include error paths. Missing: Password Recovery, Guest Checkout"
    },
    "traceability": {
      "score": 0.93,
      "weight": 0.15,
      "details": "All elements traceable except US018 (Social Login)"
    },
    "naming_coherence": {
      "score": 0.92,
      "weight": 0.10,
      "details": "2 naming conflicts: 'User' vs 'Usuário', 'ShoppingCart' vs 'Cart'"
    },
    "dependency_integrity": {
      "score": 0.98,
      "weight": 0.05,
      "details": "All dependencies respected. Warning: F012 appears before F011 in gantt chart"
    }
  },
  "warnings": [
    "Payment entity uses 'method' in ER but 'payment_type' in sequence diagram",
    "User story US018 (Social Login) has no visual representation",
    "Password Recovery flow missing error path for 'email not found'",
    "Naming inconsistency: 'User' in English vs 'Usuário' in Portuguese diagrams"
  ],
  "suggestions": [
    "Standardize Payment entity to use 'payment_method' across all diagrams",
    "Add US018 to authentication sequence diagram",
    "Add error branch to Password Recovery flowchart",
    "Choose one language (English or Portuguese) for all entity names",
    "Add F020 (Admin Dashboard) to at least one diagram",
    "Reorder F012 to appear after F011 in project timeline"
  ],
  "timestamp": "2026-03-09T10:15:30Z"
}

​

Best Practices

​

Set Appropriate Thresholds

• First project: Start with validation_threshold: 0.75 and increase as team matures
• Production systems: Use 0.85-0.90 for critical projects
• Prototypes: Can lower to 0.70 for speed

​

Use Interactive Mode Initially

​

Address High-Weight Criteria First

​

Review Suggestions

​

Iterate on Feedback

​

Error Handling

​

Integration

skills run omni-architect \
  --prd_source "./docs/my-prd.md" \
  --validation_mode "auto" \
  --validation_threshold 0.85 \
  --project_name "My Project" \
  --figma_file_key "abc123" \
  --figma_access_token "$FIGMA_TOKEN"