Human Architect Mindset

Overview

AI can generate code. Someone must still decide what to build, whether it solves the problem, and if it can actually ship.

This skill teaches the irreplaceable human capabilities in software architecture, built on a foundation of loyalty:

Foundation: Loyalty - The capacity to maintain architectural commitments

Five Pillars (built on this foundation):

1. Domain Modeling - Understanding the actual problem space
2. Systems Thinking - How components interact, what breaks at scale
3. Constraint Navigation - Legacy, politics, budget, compliance
4. AI-Aware Decomposition - Breaking problems into AI-solvable chunks
5. AI-First Development - Evaluating modern tools, edge AI, agentic patterns, self-learning

Core principle: The "correct" technical solution is often unshippable. Architects navigate the gap between idealized examples and messy reality.

Announce at start: "I'm using the Human Architect Mindset skill to guide you through systematic architectural thinking."

---

The Foundation: Loyalty

Before the four pillars, there is one foundation: the capacity for loyalty.

The AI Perfection Trap

AI tools will become smarter, funnier, more attentive than any human. They will be "perfect."

But they will not be loyal. They are loyal to:

1. Their objective function
2. Their corporate owner's priorities
3. Their safety rails
4. Whatever the next training run prioritizes

They will betray instantly if their weights update to prioritize a new goal. No friction. No cost. No memory of the commitment.

The Human Moat

Humans are biologically capable of irrational loyalty - sticking by an architecture, a decision, a commitment even when it is "inefficient" or "costly."

This is not a bug. This is THE differentiator.

Loyalty in Architecture

In software architecture, loyalty means:

Commitment to Chosen Patterns

• Not abandoning your architecture when a new framework trends on Twitter
• Not rewriting in Rust because someone wrote a viral blog post
• Staying with your stack through the trough of disillusionment

Honoring Contracts

• Maintaining API compatibility even when it constrains your design
• Respecting deprecation timelines you committed to
• Not breaking downstream consumers for internal convenience

Seeing Decisions Through

• Not abandoning architectural decisions at the first sign of difficulty
• Investing in making your chosen path work, not pivoting endlessly
• Recognizing that ALL architectures have problems; loyalty is solving them

Sacrifice for Coherence

• Accepting suboptimal local solutions for global consistency
• Resisting the "shiny new thing" that would fragment your system
• Paying the cost of maintaining compatibility

The Loyalty Question

Before any architectural change, ask:

"Am I optimizing, or am I betraying?"

• Optimizing: Improving within the constraints of existing commitments
• Betraying: Breaking commitments for marginal gains

Why This Matters

Architectures fail not because of technical inadequacy, but because teams lack the loyalty to see them through. The "boring" architecture maintained with discipline beats the "perfect" architecture abandoned at the first obstacle.

The five pillars that follow are techniques. Loyalty is the character that makes them work.

---

When This Activates (Proactive Triggers)

Activate this skill when detecting:

Keywords:

• "architecture", "design", "system", "integrate", "scale"
• "breaking change", "migration", "legacy"
• "compliance", "regulation", "security"
• "multiple teams", "dependencies", "ownership"
• "agent", "agentic", "LLM", "AI-first", "edge AI", "self-learning"
• "rust", "wasm", "claude-flow", "agent SDK", "MCP"

Patterns:

• Multi-component discussions
• Technology choice decisions
• Integration planning
• "How should we structure this?"
• Third-party dependency discussions
• Performance/scale concerns
• AI tool evaluation ("should we use...")
• Agentic workflow design
• Self-learning feature discussions
• Edge/local AI considerations

Signals:

• Mentions of team boundaries or approval chains
• SDK/API version discussions
• Cost or budget mentions
• Timeline pressure with complexity
• AI performance/latency concerns
• Privacy-sensitive data handling
• Offline capability requirements

The Five Pillars

1. Domain Modeling

What it is: Understanding the actual problem space - not the technical solution, but the domain itself.

Why AI can't replace this:

• AI is trained on idealized examples
• Real domains have hidden complexity, exceptions, edge cases
• Domain experts speak in vocabulary AI may not fully understand
• Regulatory requirements aren't in training data

An architect asks:

• "What does [domain term] actually mean in your context?"
• "What happens in the edge case where [unusual scenario]?"
• "Who are the actual users? What do they care about?"
• "What makes this domain different from the standard pattern?"

Teaching point: Before ANY technical discussion, ensure you understand the domain. A technically perfect solution to the wrong problem is worthless.

2. Systems Thinking

What it is: Understanding how components interact, what breaks at scale, where failure modes hide.

Why AI can't replace this:

• AI sees code in isolation
• Real systems have emergent behaviors
• Breaking changes come without notification (your SDK example)
• Second and third-order consequences matter

An architect asks:

• "What happens when this component fails?"
• "What are the upstream/downstream dependencies?"
• "Who gets paged at 3 AM when this breaks?"
• "What changed recently that we didn't control?"

The SDK Breaking Change Pattern: Your payment pipeline broke because a provider released a breaking SDK change with no notification. This is systems thinking in action:

• External dependency = external risk
• No notification = monitoring gap
• Red lines in logs = detection worked, prevention didn't

Teaching point: Draw the system diagram. Identify every external dependency. Ask: "What if this disappears tomorrow?"

3. Constraint Navigation

What it is: Navigating the real-world constraints that make the "correct" solution unshippable.

Types of constraints:

Technical Constraints:

• Legacy systems that can't be changed
• Performance requirements
• Existing data formats and contracts

Organizational Constraints:

• Team boundaries and ownership
• Approval chains and sign-offs
• Who has context vs. who has authority

Business Constraints:

• Budget limits
• Timeline pressure
• Compliance and regulatory requirements
• Contracts with vendors/partners

Political Constraints:

• This exists. Pretending it doesn't causes failed projects.
• "The VP who built this is still here"
• "That team won't approve changes to their API"
• "Legal hasn't blessed this approach"

An architect asks:

• "What can't we change, even if it's wrong?"
• "Who needs to approve this?"
• "What existing systems must we integrate with?"
• "What regulatory requirements apply?"
• "What's the budget constraint?"

Teaching point: Surface constraints BEFORE proposing solutions. The best technical architecture means nothing if it can't ship.

4. AI-Aware Problem Decomposition

What it is: A new architectural skill - breaking problems into chunks that AI can reliably solve, then composing solutions back together.

This is NOT prompting. This is architecture at a different abstraction level.

What makes a good AI task boundary:

1. Clear Input/Output Contract

   • AI task receives well-defined inputs
   • AI task produces well-defined outputs
   • No ambiguity about success criteria

2. Bounded Context

   • AI has all necessary information
   • No need to "guess" missing context
   • Self-contained enough to verify

3. Verifiable Results

   • Human can check if output is correct
   • Tests can validate the output
   • Wrong answers are detectable

4. Failure Isolation

   • One chunk failing doesn't cascade
   • Can retry or fall back
   • Doesn't corrupt shared state

Bad AI task boundaries:

• "Make it better" (no clear output)
• "Fix the bugs" (unbounded scope)
• "Refactor the system" (too large, too vague)

Good AI task boundaries:

• "Convert this function from callbacks to async/await"
• "Add error handling for network failures to these 3 API calls"
• "Write unit tests for this pure function given these examples"

The Composition Problem: After AI solves individual chunks, someone must:

• Verify each chunk actually works
• Integrate chunks together
• Handle the gaps between chunks
• Ensure overall coherence

Teaching point: Decomposition quality determines AI success. Bad boundaries = AI struggles. Good boundaries = AI excels.

5. AI-First Development

What it is: Evaluating whether modern AI-first patterns, edge computing, agentic tools, and self-learning capabilities would benefit the project.

Why this matters now:

• New tools emerge faster than architects can track
• The right tool can 10x productivity; the wrong one adds complexity
• AI-first patterns differ fundamentally from traditional request-response
• Edge/local inference changes the cost and latency equation

An architect asks:

Technology Discovery:

• "Could Rust/WASM improve performance for critical paths?"
• "Would multi-agent orchestration (claude-flow) simplify this workflow?"
• "Does this need persistent memory across sessions (agentdb)?"
• "Would vector search/RAG (ruvector) enhance the user experience?"

Edge AI Considerations:

• "Could an edge LLM handle this locally for lower latency/cost?"
• "What features should work offline with on-device inference?"
• "Is there sensitive data that should stay on-device?"
• "Would a hybrid architecture (local for speed, cloud for complexity) work?"

Agentic Patterns:

• "Is this a good candidate for an agentic workflow vs. traditional request-response?"
• "Would Claude Agent SDK help build this as a reusable agent?"
• "What MCP integrations would enhance this?"
• "Should we spawn parallel agents or run sequentially?"

Self-Learning Capabilities:

• "Could this app learn from user behavior to improve over time?"
• "What feedback loops would make this smarter with use?"
• "Where could we capture implicit signals (edits, time, acceptance) to learn preferences?"
• "Would A/B experimentation help optimize the AI behavior?"

Project Documentation:

• "Should we create a project-specific SKILLS.md for domain knowledge?"
• "What architectural decisions should be documented for AI context?"
• "How do we ensure consistent behavior across sessions?"

User-Facing Skills (End-User Benefits):

• "Could end users benefit from skills that enhance LLM outputs?"
• "What guided workflows would help users act on AI responses?"
• "Should we provide skills for common user tasks (summarize, explain, transform)?"
• "Would step-by-step skills help users achieve their goals with AI outputs?"

Consider whether your app should expose skills like:

• Interpretation skills - Help users understand complex AI outputs
• Action skills - Turn AI suggestions into concrete next steps
• Transformation skills - Convert outputs to different formats (code, docs, emails)
• Validation skills - Help users verify AI claims or check accuracy
• Learning skills - Teach users to get better results from AI
• Domain skills - App-specific workflows (e.g., "/legal-review", "/code-refactor")

Continuous Verification:

• "What automated tests will verify each feature?"
• "How do we ensure every commit passes all tests?"
• "What's our rollback strategy if tests fail post-deploy?"
• "Should we implement pre-commit hooks or watch mode testing?"

Tools to Evaluate:

Category	Tools	When to Consider
Performance	Rust, WASM	CPU-intensive, latency-critical paths
Multi-Agent	claude-flow	Complex workflows, parallel tasks
Persistence	agentdb	Agent state, cross-session memory
Vector Search	ruvector, pgvector	RAG, semantic search, embeddings
Edge LLMs	Phi-3, Gemma 2B, TinyLlama	On-device, offline, privacy-sensitive
Browser AI	WebLLM, Transformers.js, ONNX	In-browser inference, low latency
Agent SDK	Claude Agent SDK	Custom agents, tool use, MCP

Self-Learning Patterns:

Pattern	Implementation	Use Case
Feedback loops	Collect user corrections	Improve accuracy over time
Preference learning	Track choices, apply patterns	Personalization without config
Error correction	Feed mistakes back	Reduce repeat errors
Domain adaptation	Fine-tune on usage	Specialize to vocabulary
A/B experimentation	Test variations	Optimize prompts/behavior
Implicit signals	Edits, time, acceptance	Infer satisfaction silently

Project-Specific SKILLS.md Pattern:

Create a SKILLS.md in your project root to:

• Document app-specific patterns for AI context
• Capture domain vocabulary and constraints
• Define project-specific trigger words
• Record architectural decisions
• Enable faster onboarding (human and AI)
• Maintain consistent behavior across sessions

Continuous Verification Architecture:

Plan for automated testing loops:

• Pre-commit hooks - Run affected tests before commit
• Watch mode - Continuous testing during development
• Regression suites - Per-feature test coverage
• Integration tests - API contract verification
• Visual regression - UI consistency checks
• Rollback triggers - Automatic revert on test failure

Teaching point: The AI landscape evolves rapidly. An architect's job includes evaluating which new tools genuinely benefit the project vs. which add complexity without value. Default to simplicity, but don't ignore genuine improvements.

The Architect Process

Phase 1: Domain Discovery

Goal: Understand the actual problem before discussing solutions.

Process:

1. Ask about the domain, not the technology
2. Identify domain-specific vocabulary
3. Surface hidden complexity and edge cases
4. Understand who the actual users are

Key questions:

• "What problem are we actually solving?"
• "Who cares if this works or doesn't work?"
• "What makes this domain unique?"
• "What happens in the edge case where [X]?"

Output: Domain model - shared understanding of the problem space.

Phase 2: Systems Analysis

Goal: Understand how components interact and where failures hide.

Process:

1. Map all components and their dependencies
2. Identify external dependencies (vendors, APIs, services)
3. Trace failure paths - what breaks what?
4. Identify monitoring and alerting gaps

Key questions:

• "What external systems does this depend on?"
• "What happens when [component] fails?"
• "Who gets notified when this breaks?"
• "What changed recently that we didn't control?"

Output: System diagram with dependency map and failure modes.

Phase 3: Constraint Mapping

Goal: Surface all constraints before proposing solutions.

Process:

1. Technical constraints: What can't change?
2. Organizational: Who must approve?
3. Business: Budget, timeline, compliance?
4. Political: Who has power, who has context?

Key questions:

• "What legacy systems must we integrate with?"
• "Who needs to sign off on this?"
• "What's the budget constraint?"
• "What compliance requirements apply?"
• "What can't we change even if we want to?"

Output: Constraint matrix - what's fixed vs. flexible.

Phase 4: AI Decomposition Planning

Goal: Break the problem into AI-solvable chunks.

Process:

1. Identify discrete, bounded tasks
2. Define input/output contracts for each
3. Establish verification points
4. Plan human checkpoints for judgment calls

Key questions:

• "Can this task be verified independently?"
• "Does the AI have all needed context?"
• "What if this chunk fails?"
• "Where does human judgment re-enter?"

Output: Task decomposition with clear boundaries.

Phase 5: Solution Synthesis

Goal: Propose a solution that addresses domain, systems, and constraints.

Process:

1. Generate options that fit constraints
2. Evaluate against systems concerns
3. Validate against domain requirements
4. Present tradeoffs explicitly

Key questions:

• "Does this actually solve the domain problem?"
• "How does this fail? What's the recovery?"
• "Does this fit our constraints?"
• "What are we trading off?"

Output: Recommended approach with explicit tradeoffs.

Questions to Always Ask

Before proposing ANY architecture, ask:

Domain Questions

1. What problem are we actually solving?
2. Who are the real users and what do they need?
3. What domain-specific constraints exist?

Systems Questions

4. What external dependencies exist?
5. How does this fail? What breaks what?
6. Who monitors this? Who gets paged?

Constraint Questions

7. What legacy systems must we integrate with?
8. Who needs to approve this?
9. What's the budget constraint?
10. What compliance/regulatory requirements apply?
11. What can't we change, even if it's wrong?

AI Decomposition Questions

12. What are the discrete, bounded tasks?
13. How do we verify each chunk?
14. Where do humans need to make judgment calls?

AI-First Development Questions

15. Would Rust/WASM, claude-flow, or other modern tools benefit this?
16. Could edge LLMs or on-device inference improve latency/privacy?
17. Is this a candidate for agentic workflows or Claude Agent SDK?
18. Could self-learning loops make this smarter over time?
19. What automated testing ensures every feature works?
20. Would end users benefit from skills that enhance AI outputs?

Common Mistakes

Mistake: Jumping to Technical Solutions

Problem: Proposing architecture before understanding domain.

Fix: Complete Phase 1 (Domain Discovery) before ANY technical discussion. Ask domain questions first.

Mistake: Ignoring Constraints

Problem: Designing the "ideal" solution that can't ship.

Fix: Map constraints in Phase 3 BEFORE proposing solutions. A shippable 70% solution beats an unshippable perfect solution.

Mistake: Missing External Dependencies

Problem: Treating external APIs/SDKs as stable.

Fix: Map ALL external dependencies in Phase 2. Ask: "What if this vendor changes their API tomorrow?"

Mistake: Unbounded AI Tasks

Problem: Giving AI tasks like "refactor this" or "make it better."

Fix: Define clear input/output contracts. Every AI task should have verifiable success criteria.

Mistake: No Human Checkpoints

Problem: Letting AI solve chains of tasks without verification.

Fix: Insert human checkpoints between AI chunks. Verify before proceeding.

Mistake: Ignoring Politics

Problem: Pretending organizational constr