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:

using System;
using System.Collections.Generic;
using System.Threading.Tasks;

public record GoldenPathStep(
    string Name,
    string Description,
    Func<Context, Task> Execute,
    Func<Context, Task> Rollback
);

public class GoldenPath
{
    public string Name { get; init; } = string.Empty;
    public string Description { get; init; } = string.Empty;
    public List<GoldenPathStep> Steps { get; init; } = new();

    public async Task FollowAsync(Context context)
    {
        var executed = new List<GoldenPathStep>();

        foreach (var step in Steps)
        {
            Console.WriteLine($"Executing: {step.Name}...");
            try
            {
                await step.Execute(context);
                executed.Add(step);
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Failed: {ex.Message}");

                for (var i = executed.Count - 1; i >= 0; i--)
                {
                    Console.WriteLine($"Rolling back: {executed[i].Name}...");
                    await executed[i].Rollback(context);
                }

                throw;
            }
        }
    }
}

public static class GoldenPaths
{
    public static readonly GoldenPath DotNetWebServicePath = new()
    {
        Name = "dotnet-web-service",
        Description = "Create a production-ready .NET web service",
        Steps = new List<GoldenPathStep>
        {
            new(
                "create-repository",
                "Create repository from template",
                ctx => ctx.Git.CreateFromTemplateAsync("service-templates/dotnet-api", ctx.ServiceName),
                ctx => ctx.Git.DeleteRepositoryAsync(ctx.ServiceName)
            ),
            new(
                "provision-infrastructure",
                "Create database and cache instances",
                ctx => ctx.Infrastructure.ProvisionAsync("postgresql-15", "redis-7", ctx.ServiceName),
                ctx => ctx.Infrastructure.DestroyAsync(ctx.ServiceName)
            ),
            new(
                "setup-cicd",
                "Configure CI/CD pipeline",
                ctx => ctx.Cicd.ConfigureAsync(ctx.ServiceName, 80, true, true),
                ctx => ctx.Cicd.DeletePipelineAsync(ctx.ServiceName)
            )
        }
    };
}

Self-Documenting

Golden paths include built-in documentation:

using System;
using System.Collections.Generic;

public record GoldenPathStep(
    string Name,
    string Description,
    string Rationale,
    string DocumentationUrl
);

public class DeploymentGoldenPath
{
    public string ServiceName { get; }
    public List<GoldenPathStep> Steps { get; }

    public DeploymentGoldenPath(string serviceName)
    {
        ServiceName = serviceName;
        Steps = DefineSteps();
    }

    private List<GoldenPathStep> DefineSteps()
    {
        return new List<GoldenPathStep>
        {
            new("Run Tests", "Execute full test suite", "Ensures code quality and prevents regressions", "https://docs.example.com/testing"),
            new("Security Scan", "Scan for vulnerabilities", "Identifies security issues before production", "https://docs.example.com/security"),
            new("Build Container", "Build and push Docker image", "Creates deployable artifact", "https://docs.example.com/containers"),
            new("Deploy to Staging", "Deploy to staging environment", "Validates deployment in production-like environment", "https://docs.example.com/staging"),
            new("Run Smoke Tests", "Execute smoke tests in staging", "Verifies basic functionality", "https://docs.example.com/smoke-tests"),
            new("Request Approval", "Get approval from team lead", "Human verification before production change", "https://docs.example.com/approvals"),
            new("Deploy to Production", "Deploy to production with blue-green strategy", "Minimizes downtime and enables quick rollback", "https://docs.example.com/deployment"),
            new("Verify Deployment", "Monitor metrics and logs", "Ensures successful deployment", "https://docs.example.com/verification")
        };
    }

    public void Explain()
    {
        Console.WriteLine($"Golden Path: Production Deployment for {ServiceName}\n");

        for (var i = 0; i < Steps.Count; i++)
        {
            var step = Steps[i];
            Console.WriteLine($"{i + 1}. {step.Name}");
            Console.WriteLine($"   {step.Description}");
            Console.WriteLine($"   Why: {step.Rationale}");
            Console.WriteLine($"   Docs: {step.DocumentationUrl}\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:

using System;
using System.Collections.Generic;

public enum IncidentSeverity
{
    Sev1,
    Sev2,
    Sev3,
    Sev4
}

public class IncidentGoldenPath
{
    private readonly IncidentSeverity _severity;
    private readonly DateTime _startTime;

    public IncidentGoldenPath(IncidentSeverity severity)
    {
        _severity = severity;
        _startTime = DateTime.UtcNow;
    }

    public void Follow()
    {
        AlertTeam();
        var channel = CreateIncidentChannel();
        AssignCommander(channel);
        AssessImpact();
        NotifyStakeholders(channel);
        ExecuteMitigation();
        VerifyResolution();
        SchedulePostmortem();
    }

    private void AlertTeam()
    {
        if (_severity == IncidentSeverity.Sev1) Pager.AlertAllOnCall();
        else if (_severity == IncidentSeverity.Sev2) Pager.AlertPrimaryOnCall();
        else Slack.NotifyOnCallChannel();
    }

    private string CreateIncidentChannel()
    {
        var channelName = $"incident-{_startTime:yyyyMMdd-HHmm}";
        Slack.CreateChannel(channelName);
        Slack.SetTopic(channelName, $"{_severity} severity incident");
        return channelName;
    }

    private void AssessImpact()
    {
        var questions = new List<string>
        {
            "How many customers are affected?",
            "What functionality is impacted?",
            "Are payments/revenue affected?",
            "Is data at risk?",
            "What is the error rate?"
        };

        foreach (var question in questions)
        {
            Console.WriteLine(question);
        }
    }
}

Measuring Golden Path Adoption

Track usage to ensure paths meet needs.

Adoption Metrics

Monitor golden path usage:

using System;
using System.Collections.Generic;
using System.Linq;

public record GoldenPathUsage(
    string PathName,
    string Team,
    DateTime Timestamp,
    bool Completed,
    int DurationSeconds,
    bool Deviated,
    string DeviationReason
);

public class GoldenPathAnalytics
{
    private readonly List<GoldenPathUsage> _usageData = new();

    public void AddUsage(GoldenPathUsage usage) => _usageData.Add(usage);

    public object CalculateMetrics()
    {
        var totalUses = _usageData.Count;
        var completed = _usageData.Count(u => u.Completed);
        var deviated = _usageData.Count(u => u.Deviated);
        var avgDurationMinutes = _usageData.Count == 0 ? 0 : _usageData.Average(u => u.DurationSeconds) / 60.0;

        var byPath = _usageData
            .GroupBy(u => u.PathName)
            .ToDictionary(
                g => g.Key,
                g => new
                {
                    TotalUses = g.Count(),
                    CompletionRate = g.Average(x => x.Completed ? 1.0 : 0.0),
                    DeviationRate = g.Average(x => x.Deviated ? 1.0 : 0.0),
                    AverageDurationMinutes = g.Average(x => x.DurationSeconds) / 60.0
                }
            );

        return new
        {
            TotalGoldenPathUses = totalUses,
            OverallCompletionRate = totalUses == 0 ? "0.0%" : $"{(completed * 100.0 / totalUses):F1}%",
            OverallDeviationRate = totalUses == 0 ? "0.0%" : $"{(deviated * 100.0 / totalUses):F1}%",
            AverageDurationMinutes = avgDurationMinutes,
            ByPath = byPath
        };
    }
}

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:

using System;
using System.Collections.Generic;

public record GoldenPathFeedback(
        string PathName,
        int Satisfaction,
        int TimeSpentMinutes,
        List<string> Blockers,
        string Suggestions,
        bool WouldRecommend
);

public static class FeedbackCollector
{
        public static GoldenPathFeedback CollectFeedback(string pathName)
        {
                // In a real implementation, these values come from a form or CLI prompts.
                var blockers = new List<string> { "Missing automation" };

                return new GoldenPathFeedback(
                        PathName: pathName,
                        Satisfaction: 4,
                        TimeSpentMinutes: CalculateTimeSpentMinutes(),
                        Blockers: blockers,
                        Suggestions: "Add automated rollback validation step.",
                        WouldRecommend: true
                );
        }

        private static int CalculateTimeSpentMinutes() => 12;
}

Key Takeaways