Phase 2 (Design) Validation Skill

Purpose: Automate validation of Design Phase completion before advancing to Implementation Phase.

When to Use: When orchestrator or agents need to verify design documents are ready for implementation.

How to Use This Skill

Executable Script: execute.sh

# Basic usage with new-work directory path
bash .claude/skills/phase-2-validator/execute.sh <new-work-directory>

# With work type specification
bash .claude/skills/phase-2-validator/execute.sh <new-work-dir> <work-type>

# With custom quality gate threshold
bash .claude/skills/phase-2-validator/execute.sh <new-work-dir> Feature 90

# Examples:
bash .claude/skills/phase-2-validator/execute.sh docs/functional-areas/events/new-work/2025-11-03-feature
bash .claude/skills/phase-2-validator/execute.sh docs/functional-areas/checkin/new-work/2025-11-03-bug Bug 70

Parameters:

• new-work-directory: Path to new-work folder containing design documents
• work-type: (optional) Feature|Bug|Hotfix|Docs|Refactor (default: Feature)
• required-percentage: (optional) Override quality gate threshold

Script validates:

• Functional Specification (12 points): Technical Overview, Architecture, Data Models, API Specs, Components, Security, Testing
• Database Design (8 points): ER diagram, table schemas, migration plan, indexes, PostgreSQL types, relationships
• UI/UX Design (8 points): Wireframes, component breakdown, Mantine v7, mobile considerations, accessibility
• Integration (7 points): API endpoints match needs, database supports API, auth flow, state management, no violations

Exit codes:

• 0: Validation passed - ready for Implementation Phase
• 1: Validation failed - design incomplete

Quality Gate Checklist (90% Required for Features)

Functional Specification (12 points)

• Technical Overview section present (1 point)
• Architecture section with Web+API pattern (2 points)
• Data Models section with DTOs (2 points)
• API Specifications table present (2 points)
• Component Specifications defined (2 points)
• Security Requirements addressed (2 points)
• Testing Requirements defined (1 point)

Database Design (8 points)

• Entity Relationship Diagram present (2 points)
• Table schemas with PostgreSQL syntax (2 points)
• Migration plan defined (1 point)
• Indexes and constraints specified (1 point)
• Relationships properly defined (1 point)
• Data types appropriate for PostgreSQL (1 point)

UI/UX Design (8 points)

• Wireframes for key screens (2 points)
• Component breakdown provided (2 points)
• Mantine v7 components specified (2 points)
• Mobile responsive considerations (1 point)
• Accessibility requirements (1 point)

Integration & Technical Feasibility (7 points)

• API endpoints match component needs (2 points)
• Database schema supports API requirements (2 points)
• Authentication flow defined (1 point)
• State management approach specified (1 point)
• No architectural violations (1 point)

See: The validation logic is now in execute.sh - this maintains single source of truth for the automation.

Usage Examples

From Orchestrator

Use the phase-2-validator skill to check if design is ready for implementation

Manual Validation

# Find new-work directory
NEW_WORK_DIR=$(find docs/functional-areas -type d -path "*/new-work/*-*-*" | sort | tail -1)

# Run validation
bash .claude/skills/phase-2-validator.md "$NEW_WORK_DIR"

Common Issues

Issue: Missing Web+API Architecture

Solution: Functional spec must explicitly document:

• Web Service (React + Vite) at localhost:5173
• API Service (Minimal API) at localhost:5655
• No direct database access from Web Service

Issue: Using SQL Server Syntax

Solution: All database designs must use PostgreSQL syntax:

• ✅ UUID not UNIQUEIDENTIFIER
• ✅ VARCHAR not NVARCHAR
• ✅ TIMESTAMP not DATETIME2

Issue: Missing Mantine v7 Specification

Solution: UI design must specify Mantine components:

• Button, TextInput, Select, Modal, etc.
• No Material-UI or Chakra references

Issue: Architectural Violations

Critical violations that fail validation:

• Direct database access from Web Service
• References to Razor Pages or Blazor
• SignalR (should use HTTP polling or webhooks)
• Repository pattern over EF Core

Output Format

{
  "phase": "design",
  "status": "pass|fail",
  "score": 32,
  "maxScore": 35,
  "percentage": 91,
  "requiredPercentage": 90,
  "documents": {
    "functionalSpec": "present",
    "databaseDesign": "present",
    "uiUxDesign": "present"
  },
  "missingItems": [
    "Accessibility requirements not addressed",
    "Mobile wireframes not provided"
  ],
  "architecturalViolations": [],
  "readyForNextPhase": true
}

Integration with Quality Gates

This skill enforces the quality gate thresholds by work type:

• Feature: 90% required (32/35 points)
• Bug Fix: 70% required (25/35 points)
• Hotfix: 60% required (21/35 points)
• Documentation: 80% required (28/35 points)
• Refactoring: 85% required (30/35 points)

Progressive Disclosure

Initial Context: Show quick document checklist On Request: Show full validation script with scoring On Failure: Show specific missing items and architectural violations On Pass: Show concise summary with score

Remember: This skill automates design validation but doesn't replace agent judgment. If validation fails, orchestrator should loop back to functional-spec, database-designer, or ui-designer agents.