Setting the file. One moment.
Skill 09 · Human Architect Mindset
Subchapter 9.2
EXAMPLES.mdMarkdown23 KBView on GitHub
Real-world scenarios demonstrating the five pillars in action.
Scenario: Your payment pipeline broke. Red lines in logs. The backend provider (capital S) released a breaking SDK change with no notification.
The failure:
The gap:
Phase 2 (Systems Analysis) would have asked:
Phase 3 (Constraints) would have asked:
Current:
[App] -> [SDK v1.2] -> [Provider]
^-- Breaking change here, no warning
Better:
[App] -> [SDK Wrapper] -> [SDK vX] -> [Provider]
| ^
| |-- Version pinned, tested
|-- Abstraction layer
|-- Fallback logic
|-- Provider change monitoringAI Decomposition for Fix:
Good task boundaries:
Bad task boundary:
External dependencies are external risk. Systems thinking maps this risk BEFORE it bites.
Scenario: You need to integrate with a hospital’s EHR (Electronic Health Record) system for a healthcare app.
Domain questions an architect asks:
“What does ‘patient data’ mean in this context?”
“What’s HIPAA mean for our architecture?”
“What’s the domain vocabulary?”
“What are the edge cases?”
Technical constraints:
Organizational constraints:
Compliance constraints:
Political constraints:
Phase 1 (Domain Discovery):
Q: What problem are we solving?
A: Patients want their records accessible in our app.
Q: What's the real problem?
A: Actually, physicians want to see records from other
systems. Patients are secondary.
Q: Who needs to approve access to this data?
A: The patient (consent), the hospital (BAA), and
the physician (medical necessity).Phase 3 (Constraints):
Q: What can't we change?
A: The hospital's HL7 v2.x interface. It's 20 years old.
Q: What's the timeline?
A: 6 months, but hospital approval is 90 days.
Q: Who blocks this?
A: Hospital IT manager. Previous integration broke their system.The “correct” solution (REST API, real-time sync) is unshippable.
The shippable solution:
Good boundaries:
Bad boundaries:
Scenario: You’re building a feature that requires changes from three teams: Backend, Mobile, and Data.
The teams:
The politics:
Phase 3 (Constraint Mapping):
Q: Who needs to approve this?
A: Each team lead, plus the director for cross-team work.
Q: Who has context vs. who has authority?
A:
- Backend lead: Authority over API, context on system
- Mobile lead: Authority over app, no context on backend changes
- Data lead: Context on data flow, limited authority (new)
- Director: Authority over all, limited context on details
Q: What past decisions are politically sensitive?
A: Last cross-team project blamed Backend when it failed.
They're defensive now.
Q: What can't we change, even if it's "wrong"?
A: Mobile's 2-week release cycle. It's contractual with App Store.The “correct” technical solution:
The shippable solution:
Dependency Map:
[Mobile App] --> [Backend API] --> [Database]
|
v
[Data Pipeline] --> [Analytics]
Failure scenarios:
- Backend deploys first: Mobile shows errors (old client, new API)
- Mobile deploys first: Works but no new features
- Data deploys first: No data flowing yet
- Coordinated deploy: Single point of failure (one failure blocks all)
Better:
- Backend: Additive changes only, old endpoints stay
- Mobile: Feature flag client-side, enable when ready
- Data: Parallel pipeline, switch over when validatedTask boundaries that respect team ownership:
For Backend team:
For Mobile team:
For Data team:
Human checkpoints:
Scenario: You have a 10,000-line monolithic file that needs refactoring. You want AI to help.
Bad AI task:
"Refactor legacy_system.py into clean modules"Why it fails:
Phase 4 (AI Decomposition Planning):
Step 1: Understand the system (human work)
Q: What does this file actually do?
A: Handles user authentication, session management,
and permission checking.
Q: What are the natural boundaries?
A:
- Authentication (login, logout, password reset)
- Session (create, validate, expire)
- Permissions (check, grant, revoke)
Q: What are the dependencies between these?
A:
- Permissions depends on Session (need valid session to check)
- Session depends on Authentication (need login to create session)
- All depend on database layerStep 2: Define bounded AI tasks
Task 1: Extract authentication functions
Input: Lines 100-500 of legacy_system.py (authentication logic)
Output: auth.py with same interface, passing existing tests
Verification: All auth_test.py tests passTask 2: Extract session functions
Input: Lines 501-900 of legacy_system.py (session logic)
Output: session.py with same interface, passing existing tests
Verification: All session_test.py tests passTask 3: Extract permission functions
Input: Lines 901-1500 of legacy_system.py (permission logic)
Output: permissions.py with same interface, passing existing tests
Verification: All permission_test.py tests passStep 3: Human checkpoints
After each extraction:
Step 4: Integration (human work)
Bad:
Good:
authenticate_user function and its helpers (lines 100-200) into auth.py, maintaining the existing function signature”DatabaseError and re-raising as AuthenticationError“x on line 175 to user_session and update all references in this function”For each AI task:
1. Run existing tests (should pass before)
2. Apply AI change
3. Run existing tests (should still pass)
4. Run new tests for extracted module
5. Human review for subtle issues:
- Did AI change behavior, not just structure?
- Are there side effects not covered by tests?
- Does the change fit the overall architecture?Scenario: Product manager says “Just add a delete button to user profiles.”
Surface request: Add a delete button.
Domain questions an architect asks:
“What does ‘delete’ mean?”
“What regulations apply?”
“What happens to related data?”
Q: What depends on User?
[User Profile]
^
|-- [Posts] (has user_id foreign key)
|-- [Comments] (has user_id foreign key)
|-- [Messages] (has sender_id and recipient_id)
|-- [Orders] (has user_id, but also legal record)
|-- [Payment Methods] (PCI compliance)
|-- [Audit Logs] (compliance - can't delete)
|-- [Analytics Events] (has user_id)Cascading effects:
Technical:
Business:
Regulatory:
The “correct” solution (hard delete everything) is illegal.
Account Deletion Architecture:
1. Immediate (user-facing):
- Mark account as "deleted"
- Remove from search/listings
- Anonymize public content
- Revoke access tokens
2. 30-day window:
- User can recover account
- Data retained but inaccessible
3. After 30 days:
- Delete PII
- Retain financial records (anonymized)
- Retain audit logs (anonymized)
- Delete analytics user_id mapping
4. Never delete:
- Audit logs of deletion itself
- Financial records (7 years)Good boundaries:
deleted_at timestamp column to users table”Bad boundaries:
Scenario: Your team has used React for 3 years. A new framework (call it “HypeJS”) is trending. Benchmarks show it’s 20% faster. Twitter loves it. Your junior developers want to migrate.
“HypeJS is faster. Modern. Growing community. We should migrate.”
Commitment inventory:
What migration actually costs:
The loyalty questions:
Instead of migrating:
The loyal answer: “We committed to React. React is not our problem. Our implementation is. Let’s fix our code, not blame our framework.”
Most framework migrations are betrayals dressed as optimizations.
The loyal architect asks: “Have we truly exhausted our commitment, or are we just bored?”
Scenario: You’re building a legal document review app. Users upload contracts, the AI extracts key terms, flags risks, and suggests edits.
The questions an architect asks:
“Could performance-critical paths benefit from Rust/WASM?”
“Would multi-agent orchestration simplify this?”
“Does this need persistent memory?”
The questions:
“Could edge LLMs reduce latency or protect privacy?”
“What should work offline?”
Architecture decision:
Hybrid Architecture:
[Document] → [Local: WASM PDF Parser] → [Local: Phi-3 for initial extraction]
↓
[Privacy check: Contains PII? High confidentiality?]
↓ ↓
[Local] [Cloud]
(Gemma 2B for (Claude for complex
basic tagging) reasoning/suggestions)The questions:
“Could this app learn from user behavior?”
“What feedback loops make sense?”
Self-learning architecture:
Feedback Loop:
[AI Suggestion] → [User Action]
↓
┌───────────────────┐
│ Accept unchanged │ → High confidence signal
│ Minor edit │ → Track pattern
│ Major rewrite │ → Negative signal, learn from correction
│ Delete/ignore │ → Strong negative signal
└───────────────────┘
↓
[Aggregate feedback per user/domain]
↓
[Fine-tune prompts or model adapters]The questions:
“Would users benefit from skills that enhance AI outputs?”
/explain-clause - Explain legal jargon in plain English/compare-versions - Show differences between contract versions/risk-summary - Generate executive summary of risks/suggest-negotiation - Suggest negotiation points“What transformation skills help users?”
/export-to-word - Format AI analysis as Word document/create-checklist - Turn risks into action checklist/draft-response - Draft response to counterpartySkill architecture:
User-Facing Skills:
/explain-clause <clause>
Input: Selected clause text
Process: Simplify legal language, add examples
Output: Plain English explanation with key implications
/risk-summary
Input: Full contract analysis
Process: Aggregate risks, prioritize by severity
Output: Executive summary with top 5 risks, actions needed
/draft-response <risk>
Input: Identified risk
Process: Generate negotiation language
Output: Suggested contract edit or email responseThe questions:
“What automated tests verify each feature?”
“How do we test AI behavior?”
Testing architecture:
Continuous Verification Pipeline:
[Code Change] → [Pre-commit: Unit tests] → [CI: Integration tests]
↓
[Golden set evaluation]
↓
[Accuracy > 95%?] ──No──→ [Block deploy]
↓ Yes
[Canary deploy to 5%]
↓
[Monitor error rates 24h]
↓
[Full rollout or rollback]For this legal document app, create a SKILLS.md:
# Legal Document Assistant - Project Skills
## Domain Vocabulary
- "Clause" = Numbered paragraph in contract
- "Red flag" = High-risk term requiring attention
- "Boilerplate" = Standard language, low risk
- "Material term" = Key business term (price, dates, scope)
## AI Patterns
- Always use claude-flow for clause analysis
- Phi-3 for initial extraction, Claude for reasoning
- Minimum confidence threshold: 0.8 for auto-accept
## Testing Requirements
- All extractions must be verified against golden set
- New clause types require 10+ examples before deployment
- User feedback must be reviewed weekly
## Architectural Decisions
- Hybrid local/cloud for privacy flexibility
- Self-learning enabled, but requires 100+ signals before adaptation
- Skills exposed to users: /explain, /risk-summary, /draft-response5th Pillar applied:
| Area | Decision | Reasoning |
|---|---|---|
| Performance | Rust/WASM for PDF parsing | CPU-intensive, latency-sensitive |
| Multi-agent | claude-flow for parallel clause analysis | Independent tasks, faster processing |
| Edge AI | Phi-3/Gemma for local extraction | Privacy, offline capability |
| Cloud AI | Claude for complex reasoning | Accuracy critical for legal |
| Self-learning | Feedback loops on user actions | Improve over time, per-user/domain |
| User skills | /explain, /risk-summary, /draft-response | Help users act on AI outputs |
| Testing | Golden set + accuracy thresholds | AI behavior must be verifiable |
The lesson: AI-First Development is about evaluating which modern patterns genuinely benefit the project, not adopting everything because it’s new.
Across all examples, the architect mindset:
The “simple” solution is rarely shippable. The shippable solution is rarely simple.
And the “better” solution that betrays existing commitments is often not better at all.
Modern tools are opportunities, not requirements. Evaluate genuinely, adopt selectively.
This file