validate

name	validate
description	Run comprehensive quality checks on architecture blueprints. Validates completeness, consistency, best practices, and readiness for implementation. Identifies missing sections, conflicting decisions, and potential issues.

Blueprint Validator

Run comprehensive quality checks on your architecture blueprint to ensure it's complete, consistent, and ready for implementation.

Perfect for: Pre-implementation review, quality assurance, stakeholder review prep, team handoff

---

When to Use This Skill

Use this skill when you need to:

• Validate blueprint before sharing with stakeholders
• Check blueprint completeness before implementation
• Ensure all 19 sections are present and properly structured
• Verify consistency across sections (API → DB → Security)
• Validate against best practices
• Identify missing upgrade paths or assumptions
• Check for potential security issues
• Verify cost estimates are realistic

Input: Architecture blueprint (all 19 sections) Output: Validation report with errors, warnings, and suggestions

---

Validation Categories

1. Structural Completeness (Critical)

Check: All required sections present

Required sections (19 total):

1. Executive Summary
2. Product Type Detection
3. Tech Stack Decisions
4. Database Schema
5. Architecture Diagram
6. API Specification
7. Integrations
8. Security Architecture
9. Deployment & DevOps
10. Monitoring & Observability
11. Cost Estimate
12. Complexity Assessment
13. Service Level Objectives (SLOs)
14. Well-Architected Review
15. Sprint Backlog
16. Testing Strategy
17. Next Steps Guide
18. Required Accounts
19. Architecture Assumptions (NEW)

Errors:

• ❌ Section missing entirely
• ❌ Section header present but no content

Warnings:

• ⚠️ Section too short (< 3 paragraphs)
• ⚠️ Section lacks detail (< 500 characters)

2. Content Quality (High Priority)

Check: Each section has required subsections and details

Section 1: Executive Summary

• ✅ One-sentence product description
• ✅ Customer type (B2B/B2C)
• ✅ Problem statement
• ✅ Solution overview
• ✅ Key metrics (users, scale)
• ✅ Major assumptions called out

Section 3: Tech Stack Decisions

• ✅ Database choice with justification
• ✅ Hosting platform with cost
• ✅ Authentication provider
• ✅ All choices have confidence labels
• ✅ All choices have upgrade paths

Section 4: Database Schema

• ✅ At least 3 entities defined
• ✅ All entities have primary keys
• ✅ Foreign keys defined for relationships
• ✅ Indexes on foreign keys
• ✅ Multi-tenancy column if B2B
• ✅ Timestamps (created_at, updated_at)

Section 6: API Specification

• ✅ At least 5 endpoints documented
• ✅ All endpoints have HTTP methods
• ✅ Request/response examples provided
• ✅ Authentication requirements specified
• ✅ Error responses documented

Section 8: Security Architecture

• ✅ Authentication method specified
• ✅ Authorization strategy (RBAC, ABAC, etc.)
• ✅ Multi-tenancy isolation (if B2B)
• ✅ Secrets management approach
• ✅ OWASP Top 10 addressed

Section 11: Cost Estimate

• ✅ Infrastructure costs provided
• ✅ Cost ranges (not point estimates)
• ✅ At least 3 scenarios (MVP, Growth, Scale)
• ✅ Cost breakdown by service

Section 15: Sprint Backlog

• ✅ At least 5 sprints defined
• ✅ Each sprint has user stories
• ✅ User stories have acceptance criteria
• ✅ Story points provided
• ✅ Sprints are risk-prioritized

Section 19: Architecture Assumptions (NEW)

• ✅ All default choices documented
• ✅ Confidence labels used (Assumed/Recommended/Requires confirmation)
• ✅ Upgrade paths for each assumption
• ✅ Cost implications mentioned

3. Consistency Validation (High Priority)

Cross-section checks:

Database ↔ API Consistency

• ✅ All API endpoints reference valid database entities
• ✅ All database entities are exposed via API (or reason given)
• ❌ API returns fields not in database schema
• ❌ Database has orphaned entities (no API access)

Tech Stack ↔ Cost Estimate

• ✅ All tech stack choices appear in cost estimate
• ✅ Cost estimate matches chosen platforms
• ❌ Tech stack mentions Vercel, cost estimate shows AWS
• ❌ Database choice is PostgreSQL, cost shows MongoDB

Security ↔ Database

• ✅ If multi-tenant, database has tenant_id columns
• ✅ RLS policies mentioned if PostgreSQL + multi-tenant
• ❌ Multi-tenant product but no tenant isolation in schema

Sprint Backlog ↔ API/DB

• ✅ Sprint 0 includes database setup
• ✅ Sprints cover all major API endpoints
• ✅ Security features are prioritized early
• ❌ Sprint backlog missing critical infrastructure setup

Frontend ↔ Backend Connections

• ✅ All frontend backend_connections reference defined services
• ✅ All services consumed by frontends have endpoints documented
• ✅ Frontend client_auth.token_storage is compatible with auth strategy (e.g., cookie for web, secure-store for mobile)
• ✅ Frontend realtime.protocol matches service type (e.g., websocket service exists if frontend uses websocket)
• ❌ Frontend references a service not defined in services[]
• ❌ Frontend has no backend_connections but communicates with services via communication[]
• ⚠️ Mobile frontend missing client_auth configuration
• ⚠️ Frontend using localStorage for token storage with sensitive data (prefer cookie or secure-store)

Mobile ↔ Platform Checks

• ✅ iOS frontend has bundle_id defined
• ✅ Android frontend has bundle_id defined
• ✅ Push notification providers match platform (FCM for Android, APNS for iOS)
• ✅ Permissions listed match app functionality (camera if video calls, microphone if audio)
• ❌ Mobile frontend missing push_providers but backend has notification service
• ⚠️ Mobile frontend missing deep_link_scheme (needed for push notification deep links)
• ⚠️ Mobile frontend missing ota_updates (recommended for Expo/React Native apps)

4. Best Practices (Medium Priority)

Architecture patterns:

• ✅ Monolith recommended for new projects (not microservices)
• ✅ Managed platforms recommended over raw AWS/GCP
• ✅ PostgreSQL recommended over MongoDB for relational data
• ⚠️ Microservices for <10 engineers (premature optimization)
• ⚠️ Multiple databases in initial design (complexity)

Security:

• ✅ JWT expiration < 24 hours
• ✅ Password minimum length ≥ 8 characters
• ✅ Rate limiting on auth endpoints
• ✅ HTTPS enforced in production
• ❌ Secrets hardcoded in examples
• ❌ No rate limiting mentioned

Database:

• ✅ All foreign keys indexed
• ✅ Composite unique constraints for multi-tenant
• ✅ Soft deletes for important data
• ✅ Timestamps on all tables
• ⚠️ No indexes on frequently queried columns
• ⚠️ Missing cascade delete rules

API Design:

• ✅ RESTful naming conventions
• ✅ Pagination on list endpoints
• ✅ Proper HTTP status codes (201 for create, 204 for delete)
• ✅ API versioning strategy
• ⚠️ Inconsistent naming (camelCase vs snake_case)
• ⚠️ No filtering/sorting on list endpoints

5. Assumption-First Model Compliance (NEW)

Check: Blueprint follows Assumption-First principles

• ✅ Only 3-5 gating questions asked (not 8-12)
• ✅ All defaults have confidence labels
• ✅ All defaults have upgrade paths
• ✅ Architecture Invariants section present
• ✅ Architecture Assumptions appendix present
• ❌ Missing confidence labels on some defaults
• ❌ Missing upgrade paths for tech choices
• ⚠️ Asked for budget/timeline (should assume)

6. Upgrade Paths (Medium Priority)

Check: All decisions have upgrade paths

Required for:

• Database choice
• Hosting platform
• Architecture pattern (monolith → modular → microservices)
• Authentication provider
• Caching strategy
• File storage

Format:

**Upgrade path**: Start with [X], upgrade to [Y] when [Z]

Examples:

• ✅ "Start with Vercel, upgrade to AWS when >100K users or SOC 2 required"
• ✅ "Start with monolith, upgrade to modular monolith when >10 engineers"
• ❌ "Use PostgreSQL" (no upgrade path)
• ❌ "Use Vercel for hosting" (no scale trigger)

7. Cost Validation (Medium Priority)

Realistic cost ranges:

Infrastructure (monthly):

• MVP (< 1K users): $0-150
• Growth (1K-10K users): $150-500
• Scale (10K-100K users): $500-2000

Development (one-time):

• AI tools: $20-60/month + time
• Freelancer: $20K-60K
• Agency: $60K-150K

Errors:

• ❌ MVP costs >$500/month (too high)
• ❌ Growth tier <$100/month (too low, unrealistic)
• ❌ No cost ranges (point estimates only)
• ❌ Missing cost breakdown

8. Security Checklist (High Priority)

Check: All OWASP Top 10 addressed

1. ✅ Broken Access Control → Authorization strategy defined
2. ✅ Cryptographic Failures → Secrets management, HTTPS
3. ✅ Injection → ORM usage, parameterized queries
4. ✅ Insecure Design → Well-Architected Review
5. ✅ Security Misconfiguration → Environment variables, RLS
6. ✅ Vulnerable Components → Dependency scanning mentioned
7. ✅ Identification/Authentication → Auth provider specified
8. ✅ Software/Data Integrity → Code signing, migrations
9. ✅ Logging/Monitoring → Observability section
10. ✅ SSRF → API security, input validation

Warnings:

• ⚠️ No mention of XSS prevention
• ⚠️ No CSRF protection strategy
• ⚠️ No SQL injection mitigation (if raw SQL used)

---

Output Format

When invoked, generate:

🔍 Validating architecture blueprint...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
STRUCTURAL COMPLETENESS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ All 19 required sections present
✅ All sections have content (>500 characters)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CONTENT QUALITY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Executive Summary: Complete (product, customer, problem, solution)
✅ Tech Stack Decisions: 5 decisions with confidence labels
✅ Database Schema: 7 entities, all with PKs and indexes
✅ API Specification: 18 endpoints documented
⚠️  Security Architecture: Missing XSS prevention strategy
    → Add: "Sanitize all user input, use CSP headers"
✅ Cost Estimate: 3 scenarios ($50-150/month MVP to $500-1500/month Scale)
✅ Sprint Backlog: 8 sprints, 56 user stories, 134 story points
✅ Architecture Assumptions: All defaults with upgrade paths

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
CONSISTENCY VALIDATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Database ↔ API: All entities exposed, all endpoints valid
✅ Tech Stack ↔ Cost: All platforms in cost estimate
✅ Security ↔ Database: tenant_id columns present, RLS mentioned
❌ Sprint Backlog ↔ API: GET /analytics endpoint not in any sprint
    → Fix: Add analytics implementation to Sprint 5 or 6

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
BEST PRACTICES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Architecture: Monolith recommended (appropriate for scale)
✅ Hosting: Managed platforms (Vercel + Supabase)
✅ Database: PostgreSQL with indexes and RLS
✅ Security: JWT expiration 15 minutes, rate limiting on auth
⚠️  Database: Missing index on tickets.created_at (used for sorting)
    → Add: CREATE INDEX tickets_created_at_idx ON tickets(created_at DESC)
⚠️  API: No pagination limit enforcement (should max at 100)
    → Add: Validate limit parameter: min=1, max=100

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
ASSUMPTION-FIRST COMPLIANCE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Only 3 gating questions asked (customer type, scale, compliance)
✅ All tech defaults have confidence labels
✅ All defaults have upgrade paths
✅ Architecture Invariants section present
✅ Architecture Assumptions appendix complete
⚠️  File storage choice missing confidence label
    → Add: "Cloudflare R2 **(Recommended)** - Zero egress fees"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
UPGRADE PATHS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ Database: "PostgreSQL (Supabase) → Dedicated PostgreSQL when >100K users"
✅ Hosting: "Vercel + Railway → AWS when SOC 2 or >100K users"
✅ Architecture: "Monolith → Modular monolith when >10 engineers"
✅ Auth: "Clerk → Auth0 when enterprise SSO required"
❌ Caching: No upgrade path defined
    → Add: "Start with in-memory cache, upgrade to Redis when >10K users"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
COST VALIDATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ MVP costs: $50-150/month (realistic)
✅ Growth costs: $150-500/month (realistic)
✅ Scale costs: $500-1500/month (realistic)
✅ Cost ranges provided (not point estimates)
✅ Cost breakdown by service
⚠️  No bandwidth costs mentioned (can be significant at scale)
    → Add: Bandwidth estimate for file downloads (R2 egress is free)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
SECURITY CHECKLIST (OWASP Top 10)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✅ 1. Broken Access Control: RLS policies + RBAC
✅ 2. Cryptographic Failures: Secrets in env vars, HTTPS enforced
✅ 3. Injection: Prisma ORM (parameterized queries)
✅ 4. Insecure Design: Well-Architected Review included
✅ 5. Security Misconfiguration: Environment-based config
⚠️  6. Vulnerable Components: No dependency scanning mentioned
    → Add: "Use Dependabot or Snyk for dependency scanning"
✅ 7. Identification/Authentication: Clerk with JWT
✅ 8. Software/Data Integrity: Prisma migrations, code review
✅ 9. Logging/Monitoring: Sentry + structured logging
⚠️  10. SSRF: No mention of URL validation for integrations
    → Add: "Validate all external URLs before fetching"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
VALIDATION SUMMARY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 Score: 87/100 (Good - Ready with minor fixes)

✅ Passed: 42 checks
⚠️  Warnings: 8 (fixable, non-blocking)
❌ Errors: 2 (should fix before implementation)

🎯 Recommendation: PROCEED WITH FIXES

Priority fixes:
1. ❌ Add analytics endpoint to sprint backlog (5 min fix)
2. ❌ Define caching upgrade path (2 min fix)
3. ⚠️  Add database index on tickets.created_at (1 line)
4. ⚠️  Add API pagination limit validation (2 lines)
5. ⚠️  Add dependency scanning to DevOps section (1 paragraph)

Blueprint is 87% complete and ready for implementation after addressing 2 critical issues and 8 warnings.

Next steps:
1. Fix 2 errors (analytics sprint, caching upgrade)
2. Review 8 warnings and decide which to address
3. Re-run validation to confirm 100% pass
4. Share with stakeholders using the stakeholder presentation workflow after validation passes

---

Validation Levels

1. Strict (Default)

All errors must be fixed, warnings recommended.

Use when: Production blueprint, stakeholder review, team handoff

2. Relaxed

Warnings allowed, only errors block.

Use when: Early draft, rapid iteration, experimental designs

3. Pedantic

All warnings treated as errors.

Use when: Enterprise projects, compliance-heavy, security-critical

Examples:

# Default strict validation
/architect:sdl validate

# Relaxed (ignore warnings)
/architect:sdl validate --level=relaxed

# Pedantic (all warnings = errors)
/architect:sdl validate --level=pedantic

---

Custom Validation Rules

Add project-specific rules:

Example:

/architect:sdl validate --rules=custom-rules.yaml

custom-rules.yaml:

rules:
  - name: must_use_typescript
    severity: error
    check: tech_stack.language == "TypeScript"
    message: "All projects must use TypeScript (company policy)"

  - name: max_cost_mvp
    severity: error
    check: cost_estimate.mvp.max <= 200
    message: "MVP infrastructure costs must be <$200/month"

  - name: require_sentry
    severity: warning
    check: monitoring.includes("Sentry")
    message: "Sentry recommended for error tracking"

  - name: postgres_only
    severity: error
    check: database.type == "PostgreSQL"
    message: "Only PostgreSQL allowed (team expertise)"

---

Auto-Fix Suggestions

For common issues, suggest fixes:

Missing index:

⚠️  Missing index on tickets.created_at

Auto-fix available:
  prisma/schema.prisma:42
  Add: @@index([createdAt])

Apply fix? [y/N]

Missing upgrade path:

❌ Caching choice has no upgrade path

Auto-fix suggestion:
  Section 3, line 127
  Add: "**Upgrade path**: Start with in-memory cache (Node.js Map),
        upgrade to Redis when >10K concurrent users or when session
        sharing needed across instances."

Apply fix? [y/N]

---

Error Handling

If blueprint file not found:

• Action: Error with guidance
• Example: "❌ blueprint.md not found. Run /architect:blueprint first."

If blueprint is incomplete (< 10 sections):

• Action: Error with list of missing sections
• Example: "❌ Blueprint incomplete. Missing: Database Schema, API Spec, Security Architecture..."

If blueprint is malformed (invalid markdown):

• Action: Warning, attempt to parse anyway
• Example: "⚠️ Malformed markdown detected. Attempting to parse..."

---

Success Criteria

A passing validation should:

• ✅ All 19 sections present with content
• ✅ No critical errors (score ≥ 90/100)
• ✅ Warnings addressed or acknowledged
• ✅ Cross-section consistency validated
• ✅ Best practices followed
• ✅ Assumption-First model compliance
• ✅ All upgrade paths defined
• ✅ Cost estimates realistic
• ✅ Security checklist complete
• ✅ Ready for implementation or stakeholder review

---

Examples

Example 1: Basic Validation

/architect:sdl validate

# Output:
# 📊 Score: 87/100
# ✅ 42 checks passed
# ⚠️  8 warnings
# ❌ 2 errors

Example 2: Relaxed Mode

/architect:sdl validate --level=relaxed

# Output:
# 📊 Score: 95/100 (warnings ignored)
# ✅ 42 checks passed
# ❌ 2 errors

Example 3: With Auto-Fix

/architect:sdl validate --auto-fix

# Interactive prompts to apply suggested fixes

Example 4: Custom Rules

/architect:sdl validate --rules=company-standards.yaml

# Validates against company-specific requirements

Example 5: CI/CD Integration

# In GitHub Actions
- name: Validate Blueprint
  run: /architect:sdl validate --format=json --exit-code

# Exits with code 1 if validation fails
# Output: validation-report.json