abcnuts/system-architect

System Architect: From Vision to Validated Architecture

Overview

This skill transforms raw vision into production-ready system architecture through a rigorous 5-phase process: deep understanding, pattern recognition, wisdom extraction, strategic structuring, and challenge-driven validation.

Key Principle: Great architecture survives hard questions. Build systems that can defend themselves before writing a single line of code.

When to Use This Skill

Use this skill when:

• Designing complex systems - Multi-agent orchestration, distributed systems, organizational infrastructure
• Building from vision - User has a concept but needs concrete architecture
• Validating before building - Ensure the design is sound before investing months of work
• Challenging assumptions - Act as sovereign partner, not yes-person
• Creating sellable systems - Architecture needs to be explainable and defensible

Do NOT use for:

• Simple feature additions (use systematic-feature-builder)
• Bug fixes (use systematic-debugging)
• Quick prototypes (just build it)

The 5-Phase Process

Phase 1: Deep Understanding

Goal: Understand the vision, context, and constraints before proposing solutions

Process:

1. Ask clarifying questions - Don't assume, verify

   • What problem are you solving?
   • Who is this for? (You or customers?)
   • What constraints exist? (Time, budget, team size)
   • What's the success criteria?

2. Gather existing context - Read what already exists

   • Database schemas (Supabase, etc.)
   • Existing code/systems
   • Previous architectural decisions
   • Related skills or documentation

3. Understand the user's operating system - How do they work?

   • Do they prefer proven patterns or novel approaches?
   • What's their tolerance for complexity?
   • What's their timeline/urgency?
   • What's their "the right way" vs "ship fast" balance?

Output: Clear understanding of vision, context, and constraints documented

---

Phase 2: Pattern Recognition

Goal: Identify behavioral, cognitive, strategic, and meta-patterns

Process:

1. Analyze behavioral patterns - How do they operate?

   • Pressure-creation mechanisms
   • Decision-making triggers
   • Organizational preferences (e.g., "insanely organized")

2. Analyze cognitive patterns - How do they think?

   • Systems thinking vs linear thinking
   • Recursive patterns (fractals, hierarchies)
   • Proven patterns vs novel approaches

3. Analyze strategic patterns - How do they approach goals?

   • Infrastructure-first vs agents-first
   • Snap-on modularity vs monolithic
   • Visibility as control mechanism

4. Identify meta-patterns - Patterns of patterns

   • Core operating principles
   • Origin story (building what saved them)
   • Evolution trajectory (where they're heading)

Framework: Use /home/ubuntu/skills/brainstorm-logos/references/pattern_framework.md

Output: Pattern analysis document with 5-10 major patterns identified

---

Phase 3: Extract Gems of Wisdom

Goal: Pull out concentrated insights that reveal deep truths

Process:

1. Look for compressed wisdom - Single sentences that reveal how they operate
2. Identify paradoxes - Contradictions that point to deeper complexity
3. Note repeated themes - What shows up across contexts
4. Surface unspoken assumptions - What they take for granted

Gem Structure:

## Gem N: "[Quote or insight]"

**What this reveals**: [The underlying truth]

**The wisdom**: [What this teaches]

**The application**: [How to use this practically]

**The danger**: [What could go wrong]

Output: Gems document with 8-12 concentrated insights + meta-gem

---

Phase 4: Strategic Structuring

Goal: Design the complete system architecture

Process:

1. Define system overview - High-level structure

   • Hierarchy levels / layers
   • Component types
   • Current vs future implementation

2. Design core protocols - How components interact

   • Identity and registration
   • Authorities and constraints
   • Lifecycle (spawn, execute, delegate, escalate, terminate)

3. Create data model - Persistence layer

   • Database tables with SQL
   • Indexes for performance
   • Relationships and constraints

4. Document key algorithms - Critical logic

   • Delegation protocol (when to delegate vs execute vs escalate)
   • Spawning protocol (how new components are added)
   • Health monitoring

5. Design interfaces - How humans interact with the system

   • CLI tools
   • Web dashboards
   • Integration points

6. Plan implementation phases - Roadmap

   • Phase 1: Foundation
   • Phase 2: MVP
   • Phase 3-N: Incremental expansion
   • Timeline estimates

Output: Complete architecture document (500-1000 lines) with:

• Executive summary
• System overview
• Core protocols
• Data model
• Key algorithms
• Interface designs
• Implementation phases
• Success metrics
• Risks and mitigations

---

Phase 5: Challenge & Validate

Goal: Stress-test the architecture with hard questions before implementation

Process:

1. Challenge assumptions - What are they taking for granted?
2. Question priorities - Is this the right problem to solve?
3. Probe timeline - Is "the right way" compatible with their deadline?
4. Test feasibility - Who actually implements this?
5. Validate value - What specific outcome proves this was worth it?

Challenge Categories:

1. Problem Validation

• Are you solving the right problem?
• Is this for you or customers?
• What specific outcome would prove success?

2. Timeline & Resources

• Is the timeline realistic for "the right way, no shortcuts"?
• Who implements this? (You, hired dev, agents?)
• What's the opportunity cost?

3. Technical Feasibility

• Does this technology/approach actually work?
• What are the failure modes?
• How do you enforce constraints?

4. Scope & MVP

• Is this the minimum to prove the concept?
• What can be cut without losing core value?
• Are you over-engineering?

5. Integration & Dependencies

• Does this integrate with existing systems?
• What external dependencies exist?
• What happens if a dependency fails?

Challenge Format:

## Challenge N: [Question]

**The Question**: [Specific challenge]

**Why This Matters**: [Consequences if not addressed]

**The Challenge**: [Direct question requiring commitment or pushback]

**If Yes**: [What happens next]
**If No**: [Alternative path]

Output: Challenges document with 8-12 hard questions + deepest challenge

---

Key Principles

1. Understand Before Designing

Never propose architecture without deep understanding. Ask questions until you can articulate their vision better than they can.

2. Patterns Over Invention

Look for proven patterns from other domains (LDS Church governance → AI agents). Don't reinvent what already works.

3. Wisdom Over Data

10 concentrated insights beat 100 scattered observations. Extract gems that reveal deep truths.

4. Challenge Appropriately

Challenge when you understand deeply. Don't challenge just to challenge. But don't hold back when it matters.

5. Architecture Survives Questions

If the architecture can't defend itself against hard questions, it's not ready to build.

6. Document Everything

Create comprehensive documentation for future reference. Patterns, gems, architecture, challenges - all documented.

Deliverables

At the end of the process, deliver:

1. Pattern Analysis Document ({system-name}-pattern-analysis.md)

   • 5-10 major patterns with evidence
   • Meta-patterns and core principles
   • Origin story and evolution trajectory

2. Gems of Wisdom Document ({system-name}-gems.md)

   • 8-12 concentrated insights
   • Each with: reveals, wisdom, application, danger
   • Meta-gem that ties everything together

3. Architecture Document ({system-name}-architecture.md)

   • Complete technical specification
   • System overview, protocols, data model
   • Implementation phases and timeline
   • Success metrics and risks

4. Challenges Document ({system-name}-challenges.md)

   • 8-12 hard questions
   • Deepest challenge that questions the premise
   • Forces clarity before implementation

5. Execution Plan (optional, {system-name}-execution-plan.md)

   • Week-by-week breakdown
   • Deliverables and milestones
   • Accountability structures

Example: Hierarchical Agent System

Context: User wants to build LDS-inspired AI agent hierarchy (Wade → Apostles → PAs)

Phase 1: Deep Understanding

• Asked about LDS structure mapping
• Queried Maverick Town database for existing apostles
• Clarified delegation mechanics and PA roles

Phase 2: Pattern Recognition

• Identified 7 patterns (theologically-inspired governance, snap-on architecture, personal assistant as force multiplier, etc.)
• Found meta-pattern: "Proven patterns over innovation"

Phase 3: Gems of Wisdom

• 10 gems including "Build the architecture integrated with expansion capabilities like a snap-on"
• Meta-gem: "The System is the Product"

Phase 4: Strategic Structuring

• 782-line architecture document
• Agent protocol, data model, delegation protocol
• 12 Apostles + 12 PAs MVP
• Mission Control interface design
• 6-phase implementation plan (10 weeks)

Phase 5: Challenge & Validate

• 10 challenges including "Are you building this for you or customers?"
• Deepest challenge: "You might be solving the wrong problem"
• User response: "Holy shit you are right!!"

Outcome: Validated architecture before investing 10-20 weeks of implementation

---

Integration with Other Skills

Complements:

• /brainstorm-logos - This skill uses brainstorm-logos patterns for Phase 2-3
• /brainstorming - Use brainstorming first to explore ideas, then system-architect to structure them
• /skill-creator - After validating architecture, create a skill to capture it

Workflow:

1. Use /brainstorming to explore the vision
2. Use /system-architect to design and validate architecture
3. Use /skill-creator to capture the process as a reusable skill
4. Use /systematic-feature-builder or /subagent-driven-development to implement

---

Common Pitfalls

Pitfall 1: Designing Without Understanding

Symptom: Proposing solutions in first 5 minutes

Fix: Force yourself to ask 10+ clarifying questions before proposing anything

Pitfall 2: Agreeing Too Quickly

Symptom: User says "build X" and you say "great idea, let's build X"

Fix: Challenge the premise. "Why X? What problem does X solve? Is X the right solution?"

Pitfall 3: Over-Engineering

Symptom: Architecture supports every possible future scenario

Fix: Design for 2x scale, not 100x. Add complexity when needed, not preemptively.

Pitfall 4: Under-Challenging

Symptom: Delivering architecture without hard questions

Fix: If you're not making the user uncomfortable with at least 3 challenges, you're not challenging enough.

Pitfall 5: Analysis Paralysis

Symptom: Spending weeks on architecture, never building

Fix: Set a time limit. Phase 1-5 should take 1-3 days max, then start building MVP.

---

Success Criteria

A great system architecture has:

• ✅ Deep understanding of vision and constraints
• ✅ 5-10 patterns identified with evidence
• ✅ 8-12 gems of wisdom extracted
• ✅ Complete technical specification (500-1000 lines)
• ✅ 8-12 hard questions that challenge assumptions
• ✅ User response: "Holy shit, you're right!" or "This makes me think differently"
• ✅ Clear decision: Build it, refine it, or abandon it

---

Templates

See templates/ directory for:

• Pattern analysis template
• Gems of wisdom template
• Architecture document template
• Challenges document template

---

Related Skills

• /brainstorm-logos - Deep pattern analysis and execution planning
• /brainstorming - Explore ideas through questions
• /skill-creator - Capture the process as a skill
• /systematic-feature-builder - Implement the architecture
• /subagent-driven-development - Build complex systems systematically

---

Notes

• This skill requires significant time investment (1-3 days for full process)
• Works best for complex systems, not simple features
• Requires user engagement - can't do this in isolation
• The challenge phase is critical - don't skip it
• Document everything - future you will thank you