Validate

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