REFERENCE

The Commitment Spectrum

Architectural Loyalty Anti-Patterns

The Endless Pivot

• Symptoms: “We’re migrating to X” every 6 months
• Root cause: Lack of commitment, not lack of tools
• Fix: Commit to current stack for defined period

The Greenfield Fallacy

• Symptoms: “If we just started over…”
• Root cause: Underestimating rewrite cost, overestimating new system
• Fix: Invest in existing system instead

The Trend Chase

• Symptoms: Architecture decisions based on Hacker News front page
• Root cause: External validation over internal coherence
• Fix: Decision criteria based on YOUR context, not industry hype

The Premature Abstraction

• Symptoms: Building for hypothetical scale/requirements
• Root cause: Optimizing for imaginary future, betraying present needs
• Fix: Solve today’s problem. Evolve when needed.

The Shiny Object Syndrome

• Symptoms: Every new project uses a different stack
• Root cause: Boredom masked as technical justification
• Fix: Recognize that mastery requires commitment

Loyalty-Preserving Practices

Decision Records

• Document WHY you chose this architecture
• Reference when tempted to switch
• Update only with genuine new information

Commitment Windows

• “We will use X for at least 2 years before reconsidering”
• Creates space for learning curve and optimization
• Prevents impulse pivots

Deprecation Rituals

• Formal process for breaking commitments
• Requires justification, stakeholder notification
• Makes betrayal conscious, not casual

The Strangler Fig

• When change IS needed, evolve gradually
• New system grows around old, doesn’t replace suddenly
• Honors existing commitments while enabling transition

The Loyalty Decision Matrix

When Betrayal Is Justified (The Short List)

1. Security vulnerability that cannot be patched
2. End of life - Truly unsupported, not just old
3. Fundamental incompatibility with proven requirements
4. Acquisition/merger that forces alignment
5. Team consensus after exhausting alternatives

Even then, prefer evolution over revolution.

Spec Driven Development Templates

Constitution Template

Use this template to define unbreakable rules for a project.

Superhuman Quality Standards Table

Traceability Matrix Template

Task Specification Template

Intent Block Template

Domain Modeling Deep Dive

What Domain Modeling Actually Is

Domain modeling is understanding the problem space - not the solution space.

Solution space: APIs, databases, frameworks, deployment Problem space: Users, their needs, business rules, regulatory requirements

Most technical failures are domain failures. The code works perfectly; it just solves the wrong problem.

Domain Modeling Questions

For any new domain, ask:

1. Who are the actors?

   • Who initiates actions?
   • Who receives effects?
   • Who has authority?
   • Who has responsibility?

2. What are the entities?

   • What “things” exist in this domain?
   • What properties do they have?
   • How do they relate to each other?
   • What’s their lifecycle?

3. What are the processes?

   • What workflows exist?
   • What triggers them?
   • What are the steps?
   • What can go wrong?

4. What are the rules?

   • What constraints exist?
   • What’s allowed? What’s forbidden?
   • What exceptions exist?
   • Who can override rules?

5. What’s the vocabulary?

   • What terms have specific meanings?
   • What terms have multiple meanings?
   • What terms do users say vs. what systems call them?

Domain Discovery Techniques

Event Storming:

1. Write domain events on sticky notes (past tense: “Order Placed”)
2. Arrange chronologically
3. Identify commands that trigger events
4. Identify actors who issue commands
5. Identify aggregates (clusters of related events)

Domain Expert Interviews:

Document Analysis:

• Existing forms and workflows
• Regulatory documents
• Training materials
• Support tickets (where domain assumptions fail)

Red Flags in Domain Understanding

• Using technical terms where domain terms should be
• “Users” without specific personas
• Edge cases dismissed as “won’t happen”
• Stakeholders nodding politely but looking confused
• Domain expert correcting your terminology

Systems Thinking Patterns

The Systems Thinking Framework

Systems thinking sees relationships, not just components.

Component thinking: “The database stores user data.” Systems thinking: “Changes to user data propagate to search indexes, analytics pipelines, backup systems, and audit logs.”

Dependency Categories

1. Direct Dependencies

• What this system calls/uses
• Visible in code (imports, API calls)
• Usually documented

2. Indirect Dependencies

• What those dependencies depend on
• Not visible in your code
• Often forgotten

3. Reverse Dependencies

• What depends on this system
• Not in your code at all
• Breaking changes affect them

4. Shared Dependencies

• Resources multiple systems use
• Database, message queue, file system
• Contention and coordination issues

Failure Mode Categories

1. Crash Failures

• System stops completely
• Usually detected quickly
• Clear failure signal

2. Omission Failures

• System doesn’t respond to some requests
• May not be detected immediately
• Partial functionality

3. Timing Failures

• System responds too slowly
• Can cascade to timeouts elsewhere
• Often misdiagnosed as crash

4. Byzantine Failures

• System produces incorrect results
• Hardest to detect
• Can corrupt other systems

5. Silent Failures

• System appears to work
• Actually doing nothing (or wrong thing)
• Detected only by missing outcomes

Cascade Analysis Template

For any change, trace the cascade:

Monitoring Design

The Four Golden Signals (from Google SRE):

1. Latency: Time to serve requests
2. Traffic: Request rate
3. Errors: Rate of failed requests
4. Saturation: How full the system is

For each system, define:

• What’s normal for each signal?
• What threshold triggers alert?
• What’s the escalation path?
• What’s the runbook?

Constraint Categories Taxonomy

Technical Constraints

Existing Systems:

• APIs that can’t change
• Data formats locked by contracts
• Legacy systems without documentation
• Performance ceilings

Infrastructure:

• Deployment environment limitations
• Network topology
• Security requirements
• Disaster recovery requirements

Technical Debt:

• Systems that work but shouldn’t be extended
• Undocumented behaviors
• Workarounds that became permanent

Organizational Constraints

Team Structure:

• Who owns what
• Team boundaries
• Communication overhead
• Conway’s Law implications

Process:

• Approval chains
• Change management
• Release cycles
• Documentation requirements

Knowledge:

• Who understands what
• Bus factor
• Tribal knowledge
• Training requirements

Business Constraints

Resources:

• Budget limits
• Timeline pressure
• Headcount constraints
• Vendor contracts

Compliance:

• Industry regulations
• Legal requirements
• Audit requirements
• Data residency

Strategic:

• Product roadmap alignment
• Partnership constraints
• Competitive considerations
• Public commitments

Political Constraints

These are real. Ignoring them fails projects.

Power Dynamics:

• Who has authority
• Who has influence
• Who has veto power
• Historical conflicts

Relationships:

• Past project history
• Team reputations
• Personal relationships
• Trust levels

Incentives:

• What teams are measured on
• What individuals are rewarded for
• Risk tolerance
• Career implications

Constraint Navigation Strategies

Work Within:

• Accept constraint as given
• Design around it
• Document why

Negotiate:

• Understand why constraint exists
• Propose alternatives that address underlying need
• Get explicit agreement

Escalate:

• When constraint blocks critical path
• When cost of constraint exceeds benefit
• With clear proposal, not just complaint

Ignore:

• Almost never appropriate
• Only with explicit risk acceptance
• Document thoroughly

AI Task Boundary Patterns

What Makes a Good AI Task

Properties of well-bounded AI tasks:

1. Clear Input Specification

   • What data/context does AI receive?
   • What format is it in?
   • What’s definitely included?
   • What’s definitely excluded?

2. Clear Output Specification

   • What should AI produce?
   • What format should it be in?
   • What properties must it have?
   • What properties must it NOT have?

3. Verifiable Success Criteria

   • How do we know if output is correct?
   • Can a test verify it?
   • Can a human quickly verify it?
   • What’s an unambiguous pass/fail?

4. Bounded Scope

   • Task has clear boundaries
   • AI doesn’t need to make judgment calls
   • No “it depends” situations

5. Context Independence

   • Task doesn’t require external knowledge
   • All needed information is provided
   • No assumptions required

Task Boundary Anti-Patterns

The Vague Task:

The Unbounded Task:

The Context-Dependent Task:

The Judgment Task:

Task Decomposition Strategy

Step 1: Identify the outcome

• What’s the end state we want?
• How will we know we’re done?

Step 2: List the sub-tasks

• What discrete steps achieve this?
• What’s the dependency graph?

Step 3: For each sub-task, evaluate:

• Can AI do this with clear input/output?
• Or does this require human judgment?

Step 4: Define boundaries

• What exactly does AI receive?
• What exactly should AI produce?
• How do we verify?

Step 5: Plan integration

• How do AI outputs combine?
• Where are the gaps?
• Who handles integration?

Verification Point Design

After each AI task, verify:

1. Correctness: Does output match specification?
2. Completeness: Is anything missing?
3. Consistency: Does it fit with other components?
4. Safety: Does it introduce risks?

Verification methods:

• Automated tests: Run existing test suite
• Spot checks: Human reviews samples
• Comparison: Compare to known-good reference
• Property checks: Verify invariants hold

Composition Patterns

Sequential:

Use when: Tasks have dependencies

Parallel:

Use when: Tasks are independent

Iterative:

Use when: First attempt may need refinement

Failure Mode Analysis Templates

Pre-Mortem Template

Before implementing, answer:

Post-Mortem Template

After a failure:

Dependency Risk Matrix

Risk = Impact if fails × Likelihood of failure

For HIGH risk dependencies:

• Not done: Fallback strategy documented
• Not done: Monitoring in place
• Not done: Runbook exists
• Not done: Regular testing of failure scenario

Decision Record Template

For architectural decisions, document:

Quick Reference

The Five Questions

Before ANY architecture work:

1. What problem are we solving? (Domain)
2. What can break? (Systems)
3. What can’t we change? (Constraints)
4. How do we decompose for AI? (AI Tasks)
5. How do we verify? (Validation)

The Shippability Test

Can this ship? Check:

• Not done: Fits technical constraints
• Not done: Fits budget/timeline
• Not done: Has required approvals
• Not done: Meets compliance
• Not done: Team capacity exists

The AI Task Checklist

For each AI task:

• Not done: Input is clear
• Not done: Output is clear
• Not done: Success is verifiable
• Not done: Scope is bounded
• Not done: Context is provided