Principle Guide

Principle-based Decision Making

Guide systematic decision-making and establish principles that automate future decisions.

Core Philosophy: "Decide How to Decide"

Instead of making individual decisions repeatedly, establish principles that automate future decisions.

The Problem

Your day is filled with decisions:

• Which technology to use?
• How to structure this code?
• What approach to take?

But: Most decisions you make shouldn't require your judgment every time.

The Solution

One principle can guide a thousand decisions.

❌ Repeated Decision: "Should we use library X?"
   (Asked every time a new library is needed)

✅ Principle Established: "Use libraries with:
   - 1000+ GitHub stars
   - Active maintenance (commit in last 3 months)
   - Compatible license (MIT/Apache2)
   - Clear documentation"
   (Applies to all future library choices automatically)

Leverage

One decision → Thousand judgments automated

When to Use This Skill

Technical Decisions

• Choosing technologies (database, framework, library)
• Architectural patterns (monolith vs microservices)
• Infrastructure decisions (cloud provider, deployment strategy)
• Build vs buy decisions

Design Decisions

• API design choices
• Data model design
• Performance vs maintainability trade-offs
• Flexibility vs simplicity trade-offs

Process Decisions

• Development workflow
• Testing strategy
• Deployment process
• Code review standards

Decision Process (6 Steps)

Step 1: Define Decision Context

Questions to answer:

• What decision needs to be made?
• Why is this decision necessary?
• What constraints exist?
• Who is affected?
• What is the expected lifespan?

Template:

## Decision Context

**Decision**: [What we need to decide]
**Why**: [Problem or opportunity]
**Constraints**:
- Budget: [amount]
- Timeline: [deadline]
- Resources: [team, skills]
- Compliance: [regulations]

**Stakeholders**: [who is affected]
**Lifespan**: [how long this matters]

Step 2: Identify Alternatives

List all viable options (minimum 2, ideally 3-5):

## Alternatives

1. **Option A**: [name and brief description]
2. **Option B**: [name and brief description]
3. **Option C**: [name and brief description]
4. **Status Quo**: [do nothing / keep current]

Example:

1. PostgreSQL (RDBMS with ACID)
2. MongoDB (Document store, flexible schema)
3. DynamoDB (Managed NoSQL, AWS-specific)
4. Status Quo (Current MySQL setup)

Step 3: Define Evaluation Criteria

Common criteria:

• Performance: Latency, throughput, scalability
• Maintainability: Code clarity, team familiarity
• Cost: Initial + ongoing
• Time to market: Development + learning curve
• Risk: Technical debt, vendor lock-in
• Flexibility: Extensibility, customization

Assign weights: High (3), Medium (2), Low (1)

## Evaluation Criteria

| Criterion | Weight | Why Important |
|-----------|--------|---------------|
| Performance | High | Customer SLA: <200ms response |
| Maintainability | High | Team of 5 must maintain |
| Cost | Medium | Budget: $5K/month |
| Time to market | High | 2-month deadline |

Step 4: Score Each Alternative

Score 0-10 for each criterion with rationale.

## Trade-off Analysis

| Criterion | Weight | PostgreSQL | MongoDB | DynamoDB |
|-----------|--------|-----------|---------|----------|
| Performance | High (3) | 8/10 | 6/10 | 9/10 |
| Maintainability | High (3) | 6/10 | 9/10 | 5/10 |
| Cost | Medium (2) | 7/10 | 5/10 | 6/10 |
| Time to market | High (3) | 8/10 | 7/10 | 9/10 |

**Weighted Scores**:
- PostgreSQL: (8×3 + 6×3 + 7×2 + 8×3) / (3+3+2+3) = 7.3
- MongoDB: (6×3 + 9×3 + 5×2 + 7×3) / 11 = 6.8
- DynamoDB: (9×3 + 5×3 + 6×2 + 9×3) / 11 = 7.5

Step 5: Document Reasoning

For each score, explain why:

## Detailed Evaluation

### PostgreSQL

**Performance: 8/10**
- Handles 10K writes/sec (requirement: 5K)
- P95 latency 50ms (requirement: <200ms)
- Proven at scale

**Maintainability: 6/10**
- Team has 3 years experience ✅
- Mature ecosystem ✅
- BUT: Complex replication setup
- BUT: Requires DBA expertise

**Cost: 7/10**
- RDS: $1200/mo + backups $300/mo = $1500/mo
- Over budget ($1000/mo) but justified by reliability

[Continue for all criteria...]

Step 6: Make Recommendation

## Recommendation

**Recommended**: PostgreSQL

**Rationale**:
1. Meets critical performance requirements with margin
2. Team familiarity reduces implementation risk
3. Cost overrun ($500/mo) justified by:
   - Reduced downtime risk (current: $5K/incident)
   - Faster development (saves 1 month = $50K labor)
4. ACID compliance critical for financial data

**Trade-offs Accepted**:
- Higher cost than alternatives
- More complex operations
- **Mitigation**: Train 2 team members on PostgreSQL

**Next Steps**:
1. Prototype with RDS PostgreSQL (1 week)
2. Load testing with production data
3. Team training on best practices
4. Final decision by [date]

Establishing Principles

If this decision represents a broader pattern, establish a principle:

Principle Template

## Principle: [Short, Memorable Name]

**Context**: [When does this apply?]

**Statement**: [Clear, actionable principle]

**Rationale**: [Why this principle exists]

**Application**:
1. [How to apply in practice]
2. [Decision criteria]

**Examples**:

✅ **Good**: [Concrete example following principle]
❌ **Bad**: [Concrete example violating principle]

**Exceptions**: [When NOT to apply]

**Related Principles**: [Other relevant principles]

Example Principle

## Principle: Database Selection for OLTP

**Context**: Choosing database for transactional workloads with ACID requirements

**Statement**: Use PostgreSQL as default unless specific requirements dictate otherwise

**Rationale**:
- Team expertise (5 years experience)
- ACID compliance
- Proven at scale
- Rich ecosystem
- Avoid decision fatigue

**Application**:
1. Start with PostgreSQL
2. Switch only if:
   - Write throughput >50K/sec → Cassandra
   - Document-heavy, flexible schema → MongoDB
   - Time-series data → TimescaleDB
   - Simple key-value → Redis

**Examples**:

✅ **Good**: User service needs ACID + complex joins → PostgreSQL
❌ **Bad**: Analytics with time-series data → Should use TimescaleDB

**Exceptions**:
- Greenfield project with no ACID requirements
- Team has no PostgreSQL experience
- Graph queries needed → Neo4j

**Related Principles**:
- "Choose boring technology"
- "Optimize for team expertise"

Built-in Decision Frameworks

See FRAMEWORKS.md for detailed templates.

1. Trade-off Analysis Framework

Systematically compare alternatives with weighted criteria.

2. Build vs Buy Framework

Decision tree for build vs buy decisions:

• Core competency check
• Solution availability check
• Cost-benefit analysis

3. Technology Adoption Framework

Evaluate new technologies:

• Maturity assessment (community, maintenance, stability)
• Risk assessment
• Adoption readiness

4. Performance vs Maintainability Framework

Guide for optimization decisions:

• When to optimize (user-facing, high-scale, revenue-critical)
• When to keep simple (internal, low-traffic, acceptable performance)

5. Risk Assessment Framework

Quantify and prioritize risks:

• Risk matrix (probability × impact)
• Mitigation plans
• Residual risk calculation

Common Decision Patterns

Pattern 1: Technology Choice

1. Check if principle exists
2. Apply principle criteria
3. Document exception if needed
4. Make decision
5. Record in ADR

Pattern 2: Build vs Buy

1. Core competency check
2. Solution availability
3. Cost-benefit analysis (including opportunity cost)
4. Risk assessment
5. Decision + ADR

Pattern 3: Performance Optimization

1. Measure current state
2. Identify bottleneck
3. Calculate impact vs effort
4. Decide: optimize now vs defer
5. If optimize, isolate complexity
6. Document rationale

Integration with Other Skills

• doc-templates: Use ADR template to document decisions
• document-quality: Reviews decision documentation
• tech-doc-reviewer: Validates decision quality

After making a decision, document it:

Use doc-templates skill to create an ADR for this decision

Example Scenarios

Scenario 1: Database Choice

User: "I'm choosing between PostgreSQL and MongoDB for a new service"

Skill response:

Let's use the decision framework to guide this choice.

## Step 1: Decision Context
What are your requirements?
- ACID compliance needed?
- Query complexity (simple key-value vs complex joins)?
- Expected scale (reads/writes per second)?
- Team expertise?

## Step 2: Evaluation Criteria
Based on typical database decisions, key criteria:
- ACID compliance (if needed)
- Query capabilities
- Scale requirements
- Team expertise
- Operational complexity

[Guide through steps 3-6...]

Scenario 2: Build Custom Auth vs Auth0

User: "Should we build custom authentication or use Auth0?"

Skill response:

This is a classic Build vs Buy decision. Let's apply the framework:

## Core Competency Check
- Is authentication your core business value? [ ] Yes [ ] No
- Does custom auth provide competitive advantage? [ ] Yes [ ] No
- Do you have deep security expertise in-house? [ ] Yes [ ] No

If mostly "No", lean toward Buy (Auth0).

## Available Solutions
| Solution | Pros | Cons | Cost |
|----------|------|------|------|
| Auth0 | Proven security, low maintenance | Vendor lock-in | $200/mo |
| AWS Cognito | AWS integration, cheap | Limited features | $50/mo |
| Build Custom | Full control | High maintenance, security risk | $50K initial + $10K/mo |

[Continue analysis...]

## Recommendation
**Buy** (Auth0) because:
- Not core competency (unless you're an auth company)
- Security-critical (don't build yourself)
- Cost justified by reduced risk

Principles Library (Built-in)

Common principles for quick reference:

Technical Principles

Choose Boring Technology

• Use proven, well-understood tech
• Innovation tokens: Spend wisely (max 3 per project)

Optimize for Team Expertise

• Choose what team knows unless compelling reason
• Consider hiring difficulty and learning curve

Measure Before Optimizing

• Profile first, optimize second
• Target P95/P99, not average

Fail Fast, Fail Loudly

• Explicit error handling
• No silent failures
• Log context, not just messages

Process Principles

Test First

• Write failing test before implementation
• Refactor only when tests are green

Review Everything

• No code reaches production without review
• Review for clarity, not just correctness

Automate Toil

• If done >3 times, automate
• Invest 10% time in automation

Architecture Principles

Loose Coupling, High Cohesion

• Minimize dependencies between modules
• Group related functionality

Data at Rest, Logic in Code

• Store data, not behavior
• Avoid storing derived values (unless caching)

Explicit Over Implicit

• Make dependencies obvious
• Configuration over convention (when clarity matters)

Success Criteria

A well-guided decision includes:

• Clear context and constraints
• Multiple alternatives with trade-offs
• Explicit criteria and weights
• Scored comparison with rationale
• Recommendation with reasoning
• (Optional) Principle for future automation

Next Steps

After making a decision:

1. Document in ADR using doc-templates
2. Establish principle if pattern emerges
3. Share with team for feedback
4. Review after 3-6 months