@mytechtoday/augment-extensions 1.3.0 → 1.4.0

package/augment-extensions/workflows/adr-support/rules/template-selection.md

@@ -1,405 +1,405 @@
-# Template Selection Rules
-
-## Overview
-
-This document defines how to select the appropriate ADR template based on decision type, complexity, and context. Choosing the right template ensures ADRs are appropriately detailed without being overly burdensome.
-
-## Available Templates
-
-### 1. Michael Nygard Template (Nygard)
-
-**File:** `templates/nygard.md`
-
-**Structure:**
-- Title
-- Status
-- Context
-- Decision
-- Consequences
-
-**Best For:**
-- Simple, straightforward decisions
-- Quick decisions with clear context
-- Decisions with obvious trade-offs
-- When brevity is important
-
-**Characteristics:**
-- Minimal structure
-- Fast to complete
-- Easy to read
-- Focuses on essentials
-
-**Example Use Cases:**
-- "Use PostgreSQL for primary database"
-- "Adopt ESLint for code linting"
-- "Use JWT for authentication tokens"
-
-### 2. MADR Simple Template
-
-**File:** `templates/madr-simple.md`
-
-**Structure:**
-- Title and metadata
-- Context and Problem Statement
-- Decision Drivers
-- Considered Options
-- Decision Outcome
-- Consequences
-
-**Best For:**
-- Standard decisions (most common)
-- Decisions with 2-4 alternatives
-- When decision drivers are important
-- Balanced detail level
-
-**Characteristics:**
-- Structured but not overwhelming
-- Captures alternatives considered
-- Documents decision drivers
-- Good for team review
-
-**Example Use Cases:**
-- "Select state management library (Redux vs MobX vs Zustand)"
-- "Choose deployment platform (AWS vs Azure vs GCP)"
-- "Pick testing framework (Jest vs Vitest vs Mocha)"
-
-### 3. MADR Elaborate Template
-
-**File:** `templates/madr-elaborate.md`
-
-**Structure:**
-- Title and metadata
-- Context and Problem Statement
-- Decision Drivers
-- Considered Options (with detailed pros/cons)
-- Decision Outcome
-- Validation
-- Consequences
-- Confirmation
-
-**Best For:**
-- Complex decisions with many alternatives
-- High-stakes decisions
-- Decisions requiring detailed analysis
-- When stakeholder buy-in is critical
-
-**Characteristics:**
-- Comprehensive structure
-- Detailed pros/cons for each option
-- Validation and confirmation sections
-- Takes more time to complete
-
-**Example Use Cases:**
-- "Migrate from monolith to microservices"
-- "Select enterprise database (PostgreSQL vs Oracle vs SQL Server)"
-- "Choose cloud provider for multi-year commitment"
-
-### 4. Business Case Template
-
-**File:** `templates/business-case.md`
-
-**Structure:**
-- Executive Summary
-- Problem Statement
-- Proposed Solution
-- Cost Analysis
-- ROI Projection
-- Risk Assessment
-- Implementation Plan
-- Success Metrics
-
-**Best For:**
-- Decisions with significant cost implications
-- When ROI justification is needed
-- Vendor selection decisions
-- Budget approval required
-
-**Characteristics:**
-- Business-focused language
-- Financial analysis
-- Risk/benefit quantification
-- Executive-friendly format
-
-**Example Use Cases:**
-- "Purchase enterprise monitoring solution"
-- "Hire dedicated DevOps team"
-- "Migrate to cloud infrastructure"
-
-## Selection Decision Tree
-
-```
-Start
-  ↓
-Does decision have significant cost/ROI implications?
-  ├─ Yes → Business Case Template
-  └─ No → Continue
-       ↓
-How many alternatives are being seriously considered?
-  ├─ 1-2 → Continue
-  │         ↓
-  │    Is decision straightforward with clear trade-offs?
-  │      ├─ Yes → Nygard Template
-  │      └─ No → MADR Simple Template
-  │
-  └─ 3+ → Continue
-           ↓
-      Is this a high-stakes decision requiring detailed analysis?
-        ├─ Yes → MADR Elaborate Template
-        └─ No → MADR Simple Template
-```
-
-## Selection Criteria
-
-### Complexity Assessment
-
-**Low Complexity → Nygard**
-- Single clear option
-- Obvious trade-offs
-- Limited stakeholders
-- Low risk
-
-**Medium Complexity → MADR Simple**
-- 2-4 alternatives
-- Multiple decision drivers
-- Several stakeholders
-- Moderate risk
-
-**High Complexity → MADR Elaborate**
-- 5+ alternatives
-- Complex trade-offs
-- Many stakeholders
-- High risk/impact
-
-**Financial Focus → Business Case**
-- Significant cost
-- ROI justification needed
-- Budget approval required
-- Executive stakeholders
-
-### Decision Type Mapping
-
-| Decision Type | Recommended Template | Rationale |
-|--------------|---------------------|-----------|
-| Technology selection (simple) | Nygard | Quick, clear choice |
-| Technology selection (complex) | MADR Simple | Multiple options to evaluate |
-| Architecture pattern | MADR Elaborate | High impact, needs analysis |
-| Tool/library selection | MADR Simple | Standard evaluation process |
-| Infrastructure change | MADR Simple or Elaborate | Depends on complexity |
-| Vendor selection | Business Case | Cost and ROI important |
-| Process change | Nygard or MADR Simple | Depends on impact |
-| Security decision | MADR Elaborate | High stakes, needs detail |
-| Performance optimization | Nygard or MADR Simple | Depends on scope |
-| Deprecation decision | MADR Simple | Need to document alternatives |
-
-### Stakeholder Considerations
-
-**Few Stakeholders (1-3) → Nygard or MADR Simple**
-- Faster consensus
-- Less formal review needed
-- Can iterate quickly
-
-**Many Stakeholders (4+) → MADR Elaborate or Business Case**
-- Need comprehensive documentation
-- Formal review process
-- Multiple perspectives to capture
-
-### Time Constraints
-
-**Urgent Decision → Nygard**
-- Need to document quickly
-- Can elaborate later if needed
-- Focus on essentials
-
-**Standard Timeline → MADR Simple**
-- Balanced approach
-- Adequate time for review
-- Good detail level
-
-**Extended Timeline → MADR Elaborate or Business Case**
-- Time for thorough analysis
-- Multiple review cycles
-- Comprehensive documentation
-
-## AI Agent Selection Logic
-
-### Automatic Template Recommendation
-
-```typescript
-function recommendTemplate(decision: DecisionContext): Template {
-  // Check for financial implications
-  if (decision.hasCostImplications && decision.estimatedCost > threshold) {
-    return Template.BusinessCase;
-  }
-  
-  // Check complexity
-  const complexity = assessComplexity(decision);
-  const alternativesCount = decision.alternatives.length;
-  
-  if (complexity === 'low' && alternativesCount <= 2) {
-    return Template.Nygard;
-  }
-  
-  if (complexity === 'high' || alternativesCount >= 5) {
-    return Template.MADRElaborate;
-  }
-  
-  // Default to MADR Simple for most cases
-  return Template.MADRSimple;
-}
-
-function assessComplexity(decision: DecisionContext): 'low' | 'medium' | 'high' {
-  let score = 0;
-  
-  // Factor in various complexity indicators
-  if (decision.stakeholders.length > 5) score += 2;
-  if (decision.affectedSystems.length > 3) score += 2;
-  if (decision.isReversible === false) score += 2;
-  if (decision.riskLevel === 'high') score += 3;
-  if (decision.alternatives.length > 4) score += 2;
-  
-  if (score <= 3) return 'low';
-  if (score <= 7) return 'medium';
-  return 'high';
-}
-```
-
-### User Prompt for Template Selection
-
-```
-I recommend the MADR Simple template for this decision because:
-- You're evaluating 3 alternatives (PostgreSQL, MySQL, MongoDB)
-- Decision has moderate complexity
-- Multiple stakeholders involved
-- Standard evaluation process
-
-Would you like to:
-1. Use MADR Simple (recommended)
-2. Use Nygard (simpler, faster)
-3. Use MADR Elaborate (more detailed)
-4. Use Business Case (cost-focused)
-
-[1] [2] [3] [4]
-```
-
-## Template Switching
-
-### When to Switch Templates
-
-**Upgrade to More Detailed Template:**
-- Decision becomes more complex than initially thought
-- Additional alternatives discovered
-- Stakeholder requests more detail
-- Risk level increases
-
-**Downgrade to Simpler Template:**
-- Decision simpler than expected
-- Time constraints require faster documentation
-- Stakeholders prefer brevity
-- Low-risk decision
-
-### How to Switch Templates
-
-1. **Copy existing content** to new template
-2. **Map sections** from old to new template
-3. **Fill in additional sections** if upgrading
-4. **Preserve all context** and decisions
-5. **Update metadata** to reflect template change
-
-## Best Practices
-
-1. **Start Simple, Elaborate if Needed**
-   - Begin with Nygard or MADR Simple
-   - Upgrade if complexity warrants
-   - Don't over-engineer documentation
-
-2. **Consider Your Audience**
-   - Technical team → Nygard or MADR Simple
-   - Executive stakeholders → Business Case
-   - Mixed audience → MADR Elaborate
-
-3. **Match Template to Decision Impact**
-   - Low impact → Nygard
-   - Medium impact → MADR Simple
-   - High impact → MADR Elaborate or Business Case
-
-4. **Respect Time Constraints**
-   - Urgent → Nygard
-   - Standard → MADR Simple
-   - Extended → MADR Elaborate
-
-5. **Allow Template Override**
-   - AI recommendation is a suggestion
-   - User knows context best
-   - Support manual template selection
-
-## Examples
-
-### Example 1: Simple Decision → Nygard
-
-**Decision:** "Use Prettier for code formatting"
-
-**Why Nygard:**
-- Single clear option (Prettier)
-- Straightforward decision
-- Low complexity
-- Quick to document
-
-### Example 2: Standard Decision → MADR Simple
-
-**Decision:** "Select state management library"
-
-**Why MADR Simple:**
-- 3 alternatives (Redux, MobX, Zustand)
-- Multiple decision drivers (learning curve, bundle size, DevTools)
-- Standard evaluation process
-- Moderate complexity
-
-### Example 3: Complex Decision → MADR Elaborate
-
-**Decision:** "Migrate to microservices architecture"
-
-**Why MADR Elaborate:**
-- High-stakes decision
-- Multiple architectural patterns to consider
-- Many stakeholders (dev team, ops, management)
-- Significant consequences
-- Need detailed analysis
-
-### Example 4: Financial Decision → Business Case
-
-**Decision:** "Purchase Datadog for monitoring"
-
-**Why Business Case:**
-- Significant annual cost ($50k+)
-- ROI justification needed
-- Budget approval required
-- Executive stakeholders
-- Need cost/benefit analysis
-
-## Configuration
-
-Projects can configure template preferences in `.adr-config.json`:
-
-```json
-{
-  "templates": {
-    "default": "madr-simple",
-    "autoSelect": true,
-    "allowOverride": true,
-    "complexityThresholds": {
-      "low": 3,
-      "medium": 7
-    },
-    "costThreshold": 10000
-  }
-}
-```
-
-## See Also
-
-- [ADR Creation Guidelines](./adr-creation.md)
-- [Nygard Template](../templates/nygard.md)
-- [MADR Simple Template](../templates/madr-simple.md)
-- [MADR Elaborate Template](../templates/madr-elaborate.md)
-- [Business Case Template](../templates/business-case.md)
-
+# Template Selection Rules
+
+## Overview
+
+This document defines how to select the appropriate ADR template based on decision type, complexity, and context. Choosing the right template ensures ADRs are appropriately detailed without being overly burdensome.
+
+## Available Templates
+
+### 1. Michael Nygard Template (Nygard)
+
+**File:** `templates/nygard.md`
+
+**Structure:**
+- Title
+- Status
+- Context
+- Decision
+- Consequences
+
+**Best For:**
+- Simple, straightforward decisions
+- Quick decisions with clear context
+- Decisions with obvious trade-offs
+- When brevity is important
+
+**Characteristics:**
+- Minimal structure
+- Fast to complete
+- Easy to read
+- Focuses on essentials
+
+**Example Use Cases:**
+- "Use PostgreSQL for primary database"
+- "Adopt ESLint for code linting"
+- "Use JWT for authentication tokens"
+
+### 2. MADR Simple Template
+
+**File:** `templates/madr-simple.md`
+
+**Structure:**
+- Title and metadata
+- Context and Problem Statement
+- Decision Drivers
+- Considered Options
+- Decision Outcome
+- Consequences
+
+**Best For:**
+- Standard decisions (most common)
+- Decisions with 2-4 alternatives
+- When decision drivers are important
+- Balanced detail level
+
+**Characteristics:**
+- Structured but not overwhelming
+- Captures alternatives considered
+- Documents decision drivers
+- Good for team review
+
+**Example Use Cases:**
+- "Select state management library (Redux vs MobX vs Zustand)"
+- "Choose deployment platform (AWS vs Azure vs GCP)"
+- "Pick testing framework (Jest vs Vitest vs Mocha)"
+
+### 3. MADR Elaborate Template
+
+**File:** `templates/madr-elaborate.md`
+
+**Structure:**
+- Title and metadata
+- Context and Problem Statement
+- Decision Drivers
+- Considered Options (with detailed pros/cons)
+- Decision Outcome
+- Validation
+- Consequences
+- Confirmation
+
+**Best For:**
+- Complex decisions with many alternatives
+- High-stakes decisions
+- Decisions requiring detailed analysis
+- When stakeholder buy-in is critical
+
+**Characteristics:**
+- Comprehensive structure
+- Detailed pros/cons for each option
+- Validation and confirmation sections
+- Takes more time to complete
+
+**Example Use Cases:**
+- "Migrate from monolith to microservices"
+- "Select enterprise database (PostgreSQL vs Oracle vs SQL Server)"
+- "Choose cloud provider for multi-year commitment"
+
+### 4. Business Case Template
+
+**File:** `templates/business-case.md`
+
+**Structure:**
+- Executive Summary
+- Problem Statement
+- Proposed Solution
+- Cost Analysis
+- ROI Projection
+- Risk Assessment
+- Implementation Plan
+- Success Metrics
+
+**Best For:**
+- Decisions with significant cost implications
+- When ROI justification is needed
+- Vendor selection decisions
+- Budget approval required
+
+**Characteristics:**
+- Business-focused language
+- Financial analysis
+- Risk/benefit quantification
+- Executive-friendly format
+
+**Example Use Cases:**
+- "Purchase enterprise monitoring solution"
+- "Hire dedicated DevOps team"
+- "Migrate to cloud infrastructure"
+
+## Selection Decision Tree
+
+```
+Start
+  ↓
+Does decision have significant cost/ROI implications?
+  ├─ Yes → Business Case Template
+  └─ No → Continue
+       ↓
+How many alternatives are being seriously considered?
+  ├─ 1-2 → Continue
+  │         ↓
+  │    Is decision straightforward with clear trade-offs?
+  │      ├─ Yes → Nygard Template
+  │      └─ No → MADR Simple Template
+  │
+  └─ 3+ → Continue
+           ↓
+      Is this a high-stakes decision requiring detailed analysis?
+        ├─ Yes → MADR Elaborate Template
+        └─ No → MADR Simple Template
+```
+
+## Selection Criteria
+
+### Complexity Assessment
+
+**Low Complexity → Nygard**
+- Single clear option
+- Obvious trade-offs
+- Limited stakeholders
+- Low risk
+
+**Medium Complexity → MADR Simple**
+- 2-4 alternatives
+- Multiple decision drivers
+- Several stakeholders
+- Moderate risk
+
+**High Complexity → MADR Elaborate**
+- 5+ alternatives
+- Complex trade-offs
+- Many stakeholders
+- High risk/impact
+
+**Financial Focus → Business Case**
+- Significant cost
+- ROI justification needed
+- Budget approval required
+- Executive stakeholders
+
+### Decision Type Mapping
+
+| Decision Type | Recommended Template | Rationale |
+|--------------|---------------------|-----------|
+| Technology selection (simple) | Nygard | Quick, clear choice |
+| Technology selection (complex) | MADR Simple | Multiple options to evaluate |
+| Architecture pattern | MADR Elaborate | High impact, needs analysis |
+| Tool/library selection | MADR Simple | Standard evaluation process |
+| Infrastructure change | MADR Simple or Elaborate | Depends on complexity |
+| Vendor selection | Business Case | Cost and ROI important |
+| Process change | Nygard or MADR Simple | Depends on impact |
+| Security decision | MADR Elaborate | High stakes, needs detail |
+| Performance optimization | Nygard or MADR Simple | Depends on scope |
+| Deprecation decision | MADR Simple | Need to document alternatives |
+
+### Stakeholder Considerations
+
+**Few Stakeholders (1-3) → Nygard or MADR Simple**
+- Faster consensus
+- Less formal review needed
+- Can iterate quickly
+
+**Many Stakeholders (4+) → MADR Elaborate or Business Case**
+- Need comprehensive documentation
+- Formal review process
+- Multiple perspectives to capture
+
+### Time Constraints
+
+**Urgent Decision → Nygard**
+- Need to document quickly
+- Can elaborate later if needed
+- Focus on essentials
+
+**Standard Timeline → MADR Simple**
+- Balanced approach
+- Adequate time for review
+- Good detail level
+
+**Extended Timeline → MADR Elaborate or Business Case**
+- Time for thorough analysis
+- Multiple review cycles
+- Comprehensive documentation
+
+## AI Agent Selection Logic
+
+### Automatic Template Recommendation
+
+```typescript
+function recommendTemplate(decision: DecisionContext): Template {
+  // Check for financial implications
+  if (decision.hasCostImplications && decision.estimatedCost > threshold) {
+    return Template.BusinessCase;
+  }
+  
+  // Check complexity
+  const complexity = assessComplexity(decision);
+  const alternativesCount = decision.alternatives.length;
+  
+  if (complexity === 'low' && alternativesCount <= 2) {
+    return Template.Nygard;
+  }
+  
+  if (complexity === 'high' || alternativesCount >= 5) {
+    return Template.MADRElaborate;
+  }
+  
+  // Default to MADR Simple for most cases
+  return Template.MADRSimple;
+}
+
+function assessComplexity(decision: DecisionContext): 'low' | 'medium' | 'high' {
+  let score = 0;
+  
+  // Factor in various complexity indicators
+  if (decision.stakeholders.length > 5) score += 2;
+  if (decision.affectedSystems.length > 3) score += 2;
+  if (decision.isReversible === false) score += 2;
+  if (decision.riskLevel === 'high') score += 3;
+  if (decision.alternatives.length > 4) score += 2;
+  
+  if (score <= 3) return 'low';
+  if (score <= 7) return 'medium';
+  return 'high';
+}
+```
+
+### User Prompt for Template Selection
+
+```
+I recommend the MADR Simple template for this decision because:
+- You're evaluating 3 alternatives (PostgreSQL, MySQL, MongoDB)
+- Decision has moderate complexity
+- Multiple stakeholders involved
+- Standard evaluation process
+
+Would you like to:
+1. Use MADR Simple (recommended)
+2. Use Nygard (simpler, faster)
+3. Use MADR Elaborate (more detailed)
+4. Use Business Case (cost-focused)
+
+[1] [2] [3] [4]
+```
+
+## Template Switching
+
+### When to Switch Templates
+
+**Upgrade to More Detailed Template:**
+- Decision becomes more complex than initially thought
+- Additional alternatives discovered
+- Stakeholder requests more detail
+- Risk level increases
+
+**Downgrade to Simpler Template:**
+- Decision simpler than expected
+- Time constraints require faster documentation
+- Stakeholders prefer brevity
+- Low-risk decision
+
+### How to Switch Templates
+
+1. **Copy existing content** to new template
+2. **Map sections** from old to new template
+3. **Fill in additional sections** if upgrading
+4. **Preserve all context** and decisions
+5. **Update metadata** to reflect template change
+
+## Best Practices
+
+1. **Start Simple, Elaborate if Needed**
+   - Begin with Nygard or MADR Simple
+   - Upgrade if complexity warrants
+   - Don't over-engineer documentation
+
+2. **Consider Your Audience**
+   - Technical team → Nygard or MADR Simple
+   - Executive stakeholders → Business Case
+   - Mixed audience → MADR Elaborate
+
+3. **Match Template to Decision Impact**
+   - Low impact → Nygard
+   - Medium impact → MADR Simple
+   - High impact → MADR Elaborate or Business Case
+
+4. **Respect Time Constraints**
+   - Urgent → Nygard
+   - Standard → MADR Simple
+   - Extended → MADR Elaborate
+
+5. **Allow Template Override**
+   - AI recommendation is a suggestion
+   - User knows context best
+   - Support manual template selection
+
+## Examples
+
+### Example 1: Simple Decision → Nygard
+
+**Decision:** "Use Prettier for code formatting"
+
+**Why Nygard:**
+- Single clear option (Prettier)
+- Straightforward decision
+- Low complexity
+- Quick to document
+
+### Example 2: Standard Decision → MADR Simple
+
+**Decision:** "Select state management library"
+
+**Why MADR Simple:**
+- 3 alternatives (Redux, MobX, Zustand)
+- Multiple decision drivers (learning curve, bundle size, DevTools)
+- Standard evaluation process
+- Moderate complexity
+
+### Example 3: Complex Decision → MADR Elaborate
+
+**Decision:** "Migrate to microservices architecture"
+
+**Why MADR Elaborate:**
+- High-stakes decision
+- Multiple architectural patterns to consider
+- Many stakeholders (dev team, ops, management)
+- Significant consequences
+- Need detailed analysis
+
+### Example 4: Financial Decision → Business Case
+
+**Decision:** "Purchase Datadog for monitoring"
+
+**Why Business Case:**
+- Significant annual cost ($50k+)
+- ROI justification needed
+- Budget approval required
+- Executive stakeholders
+- Need cost/benefit analysis
+
+## Configuration
+
+Projects can configure template preferences in `.adr-config.json`:
+
+```json
+{
+  "templates": {
+    "default": "madr-simple",
+    "autoSelect": true,
+    "allowOverride": true,
+    "complexityThresholds": {
+      "low": 3,
+      "medium": 7
+    },
+    "costThreshold": 10000
+  }
+}
+```
+
+## See Also
+
+- [ADR Creation Guidelines](./adr-creation.md)
+- [Nygard Template](../templates/nygard.md)
+- [MADR Simple Template](../templates/madr-simple.md)
+- [MADR Elaborate Template](../templates/madr-elaborate.md)
+- [Business Case Template](../templates/business-case.md)
+