Golden Paths

Golden paths are well-paved, opinionated workflows that guide teams through common development tasks using platform best practices. They reduce cognitive load by providing clear, tested routes to accomplish goals while maintaining flexibility for special cases.

Understanding Golden Paths

A golden path represents the recommended way to accomplish a task on the platform.

The Decision Fatigue Problem

Without guidance, teams face overwhelming choices:

Creating a New Service Without Golden Path:
├── Which language/framework?
├── Which testing library?
├── How to structure the code?
├── Which base Docker image?
├── How to configure logging?
├── Which metrics library?
├── How to setup CI/CD?
├── How to manage secrets?
├── Which deployment tool?
├── How to configure monitoring?
└── ... 50+ more decisions

Each decision requires research, potentially leading to analysis paralysis or suboptimal choices.

Golden Path Benefits

Clear, opinionated defaults:

graph LR
    A[Developer Goal:
Deploy New Service] --> B[Golden Path]
    
    B --> C[Template Selected]
    B --> D[Tests Configured]
    B --> E[Pipeline Generated]
    B --> F[Monitoring Setup]
    
    C --> G[Service Running
in 30 minutes]
    D --> G
    E --> G
    F --> G
    
    style B fill:#e1f5ff
    style G fill:#d4f1d4

Characteristics of Golden Paths

Effective golden paths share common attributes.

Opinionated but Flexible

Strong defaults with escape hatches:

# Golden path for Python web services
apiVersion: platform.example.com/v1
kind: GoldenPath
metadata:
  name: python-web-service
  description: Standard path for Python web services
spec:
  defaults:
    # Opinionated choices
    framework: fastapi
    python_version: "3.11"
    testing_framework: pytest
    linting: ruff
    formatting: black
    metrics: prometheus-client
    logging: structlog
    
    # Infrastructure defaults
    database: postgresql-15
    cache: redis-7
    container_registry: ghcr.io
    deployment_tool: argocd
    
    # CI/CD defaults
    ci_provider: github-actions
    test_coverage_threshold: 80
    security_scanning: true
    
  customization:
    # Allow customization with justification
    allowed_frameworks:
      - fastapi  # Default
      - flask    # Allowed for legacy compatibility
      - django   # Allowed for admin-heavy apps
    
    # Some choices are fixed
    python_version:
      fixed: true
      reason: "Standardized across platform"
    
    logging:
      fixed: true
      reason: "Required for centralized log aggregation"

Paved with Automation

Golden paths leverage automation:

# Single command follows golden path
platform create service my-api \
  --golden-path python-web-service

# Behind the scenes:
# 1. Creates Git repository from template
# 2. Configures branch protection rules
# 3. Sets up CI/CD pipeline
# 4. Provisions development infrastructure
# 5. Creates monitoring dashboards
# 6. Registers in service catalog
# 7. Sets up initial documentation

Implementation:

// Golden path orchestrator
package platform

type GoldenPath struct {
    Name        string
    Description string
    Steps       []Step
}

type Step struct {
    Name        string
    Description string
    Execute     func(context Context) error
    Rollback    func(context Context) error
}

func (gp *GoldenPath) Follow(context Context) error {
    executed := []Step{}
    
    for _, step := range gp.Steps {
        fmt.Printf("Executing: %s...\n", step.Name)
        
        if err := step.Execute(context); err != nil {
            fmt.Printf("Failed: %s\n", err)
            
            // Rollback executed steps
            for i := len(executed) - 1; i >= 0; i-- {
                fmt.Printf("Rolling back: %s...\n", executed[i].Name)
                executed[i].Rollback(context)
            }
            
            return err
        }
        
        executed = append(executed, step)
    }
    
    return nil
}

var PythonWebServicePath = &GoldenPath{
    Name:        "python-web-service",
    Description: "Create a production-ready Python web service",
    Steps: []Step{
        {
            Name:        "create-repository",
            Description: "Create GitHub repository from template",
            Execute: func(ctx Context) error {
                return ctx.GitHub.CreateFromTemplate(
                    "service-templates/python-fastapi",
                    ctx.ServiceName,
                )
            },
            Rollback: func(ctx Context) error {
                return ctx.GitHub.DeleteRepository(ctx.ServiceName)
            },
        },
        {
            Name:        "provision-infrastructure",
            Description: "Create database and cache instances",
            Execute: func(ctx Context) error {
                return ctx.Infrastructure.Provision(InfrastructureSpec{
                    Database: "postgresql-15",
                    Cache:    "redis-7",
                    Service:  ctx.ServiceName,
                })
            },
            Rollback: func(ctx Context) error {
                return ctx.Infrastructure.Destroy(ctx.ServiceName)
            },
        },
        {
            Name:        "setup-cicd",
            Description: "Configure CI/CD pipeline",
            Execute: func(ctx Context) error {
                return ctx.CICD.Configure(PipelineConfig{
                    Service:       ctx.ServiceName,
                    TestCoverage:  80,
                    SecurityScan:  true,
                    AutoDeploy:    true,
                })
            },
            Rollback: func(ctx Context) error {
                return ctx.CICD.DeletePipeline(ctx.ServiceName)
            },
        },
        {
            Name:        "setup-monitoring",
            Description: "Create dashboards and alerts",
            Execute: func(ctx Context) error {
                return ctx.Monitoring.Setup(MonitoringConfig{
                    Service:    ctx.ServiceName,
                    Dashboards: []string{"standard-service"},
                    Alerts:     []string{"high-error-rate", "high-latency"},
                })
            },
            Rollback: func(ctx Context) error {
                return ctx.Monitoring.DeleteConfig(ctx.ServiceName)
            },
        },
        {
            Name:        "register-catalog",
            Description: "Register service in catalog",
            Execute: func(ctx Context) error {
                return ctx.Catalog.Register(CatalogEntry{
                    Name:  ctx.ServiceName,
                    Type:  "service",
                    Owner: ctx.Team,
                })
            },
            Rollback: func(ctx Context) error {
                return ctx.Catalog.Unregister(ctx.ServiceName)
            },
        },
    },
}

Self-Documenting

Golden paths include built-in documentation:

# Golden path with inline documentation
from dataclasses import dataclass
from typing import List

@dataclass
class GoldenPathStep:
    name: str
    description: str
    rationale: str
    documentation_url: str
    
class DeploymentGoldenPath:
    """
    Golden path for deploying services to production.
    
    This path ensures all production requirements are met:
    - Security scanning completed
    - Tests passing with >80% coverage
    - Manual approval obtained
    - Rollback plan documented
    """
    
    def __init__(self, service_name: str):
        self.service_name = service_name
        self.steps = self._define_steps()
    
    def _define_steps(self) -> List[GoldenPathStep]:
        return [
            GoldenPathStep(
                name="Run Tests",
                description="Execute full test suite",
                rationale="Ensures code quality and prevents regressions",
                documentation_url="https://docs.example.com/testing"
            ),
            GoldenPathStep(
                name="Security Scan",
                description="Scan for vulnerabilities",
                rationale="Identifies security issues before production",
                documentation_url="https://docs.example.com/security"
            ),
            GoldenPathStep(
                name="Build Container",
                description="Build and push Docker image",
                rationale="Creates deployable artifact",
                documentation_url="https://docs.example.com/containers"
            ),
            GoldenPathStep(
                name="Deploy to Staging",
                description="Deploy to staging environment",
                rationale="Validates deployment in production-like environment",
                documentation_url="https://docs.example.com/staging"
            ),
            GoldenPathStep(
                name="Run Smoke Tests",
                description="Execute smoke tests in staging",
                rationale="Verifies basic functionality",
                documentation_url="https://docs.example.com/smoke-tests"
            ),
            GoldenPathStep(
                name="Request Approval",
                description="Get approval from team lead",
                rationale="Human verification before production change",
                documentation_url="https://docs.example.com/approvals"
            ),
            GoldenPathStep(
                name="Deploy to Production",
                description="Deploy to production with blue-green strategy",
                rationale="Minimizes downtime and enables quick rollback",
                documentation_url="https://docs.example.com/deployment"
            ),
            GoldenPathStep(
                name="Verify Deployment",
                description="Monitor metrics and logs",
                rationale="Ensures successful deployment",
                documentation_url="https://docs.example.com/verification"
            ),
        ]
    
    def explain(self):
        """Print explanation of the golden path"""
        print(f"Golden Path: Production Deployment for {self.service_name}\n")
        
        for i, step in enumerate(self.steps, 1):
            print(f"{i}. {step.name}")
            print(f"   {step.description}")
            print(f"   Why: {step.rationale}")
            print(f"   Docs: {step.documentation_url}\n")

Common Golden Paths

Platform teams typically define golden paths for frequent tasks.

Service Creation Path

End-to-end service creation:

sequenceDiagram
    participant D as Developer
    participant P as Platform CLI
    participant G as GitHub
    participant I as Infrastructure
    participant C as CI/CD
    
    D->>P: platform create service my-api
    P->>P: Validate service name
    P->>G: Create repo from template
    G-->>P: Repository URL
    P->>I: Provision database & cache
    I-->>P: Connection strings
    P->>C: Setup pipeline
    C-->>P: Pipeline configured
    P->>P: Generate .env file
    P->>P: Commit initial code
    P-->>D: Service ready! Next: cd my-api && git push
    
    Note over D,C: Total time: 2 minutes

Database Migration Path

Safe database changes:

# Golden path: Database migration
name: database-migration-path
description: Safely apply database schema changes

steps:
  - name: create-migration
    command: |
      platform db migration create \
        --service my-api \
        --name add_user_preferences
    
    generates: migrations/001_add_user_preferences.sql
    
  - name: test-migration-locally
    command: |
      platform db migration test \
        --service my-api \
        --file migrations/001_add_user_preferences.sql
    
    verification:
      - Migration applies successfully
      - Migration rolls back successfully
      - No data loss in rollback
  
  - name: code-review
    description: Get migration reviewed by database expert
    
    checklist:
      - [ ] Migration is idempotent
      - [ ] Rollback is safe
      - [ ] Indexes added for new queries
      - [ ] No blocking operations on large tables
      - [ ] Performance impact assessed
  
  - name: apply-to-staging
    command: |
      platform db migration apply \
        --service my-api \
        --environment staging \
        --file migrations/001_add_user_preferences.sql
    
    monitoring:
      - Watch for slow query alerts
      - Monitor database CPU/memory
      - Check application error rates
  
  - name: validate-staging
    description: Verify migration in staging environment
    
    tests:
      - Run integration tests
      - Verify new queries perform well
      - Check application functionality
  
  - name: schedule-production
    command: |
      platform db migration schedule \
        --service my-api \
        --environment production \
        --file migrations/001_add_user_preferences.sql \
        --time "2024-08-20T02:00:00Z"
    
    notification: Team notified of scheduled migration
  
  - name: apply-to-production
    description: Automated execution at scheduled time
    
    safeguards:
      - Automatic backup before migration
      - Monitoring alerts active
      - Rollback plan ready
      - On-call engineer notified
  
  - name: post-deployment-verification
    monitoring_window: 24 hours
    
    watch_for:
      - Error rate increases
      - Performance degradation
      - Database connection issues

Incident Response Path

Structured incident handling:

# Golden path for incident response
from enum import Enum
from datetime import datetime

class IncidentSeverity(Enum):
    SEV1 = "critical"    # Customer-facing outage
    SEV2 = "high"        # Degraded service
    SEV3 = "medium"      # Minor issues
    SEV4 = "low"         # Cosmetic issues

class IncidentGoldenPath:
    """
    Golden path for handling production incidents.
    Ensures consistent, effective incident response.
    """
    
    def __init__(self, severity: IncidentSeverity):
        self.severity = severity
        self.start_time = datetime.now()
    
    def follow(self):
        """Execute incident response golden path"""
        
        # Step 1: Alert and assemble team
        self.alert_team()
        
        # Step 2: Create incident channel
        channel = self.create_incident_channel()
        
        # Step 3: Assign incident commander
        commander = self.assign_commander()
        
        # Step 4: Initial assessment
        self.assess_impact()
        
        # Step 5: Communication
        self.notify_stakeholders()
        
        # Step 6: Mitigation
        self.execute_mitigation()
        
        # Step 7: Verification
        self.verify_resolution()
        
        # Step 8: Post-incident
        self.schedule_postmortem()
    
    def alert_team(self):
        """Alert on-call team based on severity"""
        if self.severity == IncidentSeverity.SEV1:
            # Page entire on-call rotation
            pager.alert_all_on_call()
        elif self.severity == IncidentSeverity.SEV2:
            # Page primary on-call
            pager.alert_primary_on_call()
        else:
            # Slack notification
            slack.notify_on_call_channel()
    
    def create_incident_channel(self) -> str:
        """Create dedicated Slack channel for incident"""
        channel_name = f"incident-{self.start_time.strftime('%Y%m%d-%H%M')}"
        
        slack.create_channel(channel_name)
        slack.set_topic(channel_name, f"{self.severity.value} severity incident")
        slack.invite_on_call_team(channel_name)
        
        # Pin important links
        slack.pin_message(channel_name, """
        Incident Resources:
        - Runbooks: https://runbooks.example.com
        - Metrics: https://grafana.example.com
        - Logs: https://logs.example.com
        - Status Page: https://status.example.com
        """)
        
        return channel_name
    
    def assess_impact(self):
        """Assess incident impact"""
        questions = [
            "How many customers are affected?",
            "What functionality is impacted?",
            "Are payments/revenue affected?",
            "Is data at risk?",
            "What is the error rate?"
        ]
        
        # Collect answers and document
        for question in questions:
            answer = input(f"{question}: ")
            self.document_finding(question, answer)

Measuring Golden Path Adoption

Track usage to ensure paths meet needs.

Adoption Metrics

Monitor golden path usage:

# Golden path analytics
from dataclasses import dataclass
from datetime import datetime

@dataclass
class GoldenPathUsage:
    path_name: str
    team: str
    timestamp: datetime
    completed: bool
    duration_seconds: int
    deviated: bool
    deviation_reason: str

class GoldenPathAnalytics:
    def __init__(self):
        self.usage_data = []
    
    def calculate_metrics(self) -> dict:
        """Calculate golden path effectiveness metrics"""
        
        total_uses = len(self.usage_data)
        completed = sum(1 for u in self.usage_data if u.completed)
        deviated = sum(1 for u in self.usage_data if u.deviated)
        
        avg_duration = sum(
            u.duration_seconds for u in self.usage_data
        ) / total_uses
        
        # Group by path
        path_stats = {}
        for path in set(u.path_name for u in self.usage_data):
            path_uses = [u for u in self.usage_data if u.path_name == path]
            
            path_stats[path] = {
                'total_uses': len(path_uses),
                'completion_rate': sum(1 for u in path_uses if u.completed) / len(path_uses),
                'deviation_rate': sum(1 for u in path_uses if u.deviated) / len(path_uses),
                'avg_duration_minutes': sum(u.duration_seconds for u in path_uses) / len(path_uses) / 60
            }
        
        return {
            'total_golden_path_uses': total_uses,
            'overall_completion_rate': f"{(completed / total_uses) * 100:.1f}%",
            'overall_deviation_rate': f"{(deviated / total_uses) * 100:.1f}%",
            'average_duration_minutes': avg_duration / 60,
            'by_path': path_stats
        }

Deviation analysis:

Common Deviation Reasons:
├── 35% - Special security requirements
├── 25% - Legacy system integration
├── 20% - Performance optimization needed
├── 15% - Regulatory compliance
└── 5% - Personal preference

Action: Update golden paths to accommodate top 3 reasons

Evolving Golden Paths

Golden paths must evolve with platform maturity.

Feedback Loop

Continuous improvement cycle:

graph TD
    A[Golden Path Published] --> B[Teams Use Path]
    B --> C[Collect Feedback]
    C --> D[Analyze Deviations]
    D --> E{Path Issues?}
    
    E -->|Yes| F[Update Golden Path]
    E -->|No| G[Path Working Well]
    
    F --> H[Communicate Changes]
    G --> H
    
    H --> B
    
    style F fill:#fff4cc
    style G fill:#d4f1d4

Feedback collection:

// Feedback collection after golden path completion
interface GoldenPathFeedback {
  pathName: string;
  satisfaction: number;  // 1-5
  timeSpent: number;     // minutes
  blockers: string[];
  suggestions: string;
  wouldRecommend: boolean;
}

async function collectFeedback(pathName: string): Promise<GoldenPathFeedback> {
  const feedback = await prompt([
    {
      type: 'rating',
      name: 'satisfaction',
      message: 'How satisfied are you with this golden path?',
      scale: 5
    },
    {
      type: 'checkbox',
      name: 'blockers',
      message: 'Did you encounter any blockers?',
      choices: [
        'Unclear documentation',
        'Missing automation',
        'Too rigid/inflexible',
        'Technical issues',
        'Required manual intervention',
        'None'
      ]
    },
    {
      type: 'text',
      name: 'suggestions',
      message: 'How could this golden path be improved?'
    },
    {
      type: 'confirm',
      name: 'wouldRecommend',
      message: 'Would you recommend this path to other teams?'
    }
  ]);
  
  return {
    pathName,
    ...feedback,
    timeSpent: calculateTimeSpent()
  };
}

Key Takeaways