golden-paths

What this skill does

# Golden Paths

Patterns for designing standardized, opinionated development workflows that make the right way the easy way.

## When to Use This Skill

- Designing standardized developer workflows
- Creating paved roads for common patterns
- Building template-based service creation
- Implementing guardrails with flexibility
- Optimizing developer onboarding
- Reducing cognitive load for developers

## Golden Path Fundamentals

### What is a Golden Path?

```text
Golden Path Definition:
An opinionated, well-supported workflow that makes best practices
the path of least resistance while not blocking alternatives.

Key Characteristics:
┌─────────────────────────────────────────────────────────────┐
│                    GOLDEN PATH                               │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ✓ Opinionated:  Clear decisions made for you               │
│  ✓ Supported:    First-class documentation and tooling      │
│  ✓ Optimized:    Fastest path to production                 │
│  ✓ Maintained:   Kept up-to-date by platform team           │
│  ✓ Escapable:    Can deviate when needed                    │
│                                                              │
│  "Make the right way the easy way"                          │
│                                                              │
│  Golden Path ≠ The Only Path                                │
│  Golden Path = The Recommended Path                         │
│                                                              │
└─────────────────────────────────────────────────────────────┘

vs Paved Road vs Rails:
├── Golden Path: Recommended workflow with alternatives
├── Paved Road: Same concept, Spotify terminology
├── Rails: More rigid, harder to deviate (often negative)
```

### Golden Path vs Custom

```text
Golden Path Benefits:

Developer Time:
├── New service: 15 min (golden) vs 2 days (custom)
├── Setup CI/CD: Automatic vs 4-8 hours
├── Observability: Built-in vs manual integration
└── Security: Automatic vs checklist review

Platform Support:
├── Golden path: Full support, rapid fixes
├── Custom: Best-effort support, lower priority
├── Hybrid: Support for platform components only

Example Journey:

Golden Path:
┌─────────────────────────────────────────────────────────────┐
│ 1. Choose template     → node-api-template                  │
│ 2. Answer questions    → name, team, database?             │
│ 3. Generate repo       → automatic                         │
│ 4. First deployment    → automatic via CI                  │
│ 5. Start coding        → focus on business logic           │
│                                                              │
│ Time: ~15 minutes                                           │
│ Result: Production-ready service                            │
└─────────────────────────────────────────────────────────────┘

Custom Path:
┌─────────────────────────────────────────────────────────────┐
│ 1. Create repo         → manual setup                       │
│ 2. Choose framework    → research options                   │
│ 3. Setup build         → configure bundler/compiler         │
│ 4. Add observability   → integrate logging, metrics         │
│ 5. Security review     → checklist, manual fixes            │
│ 6. Setup CI/CD         → write pipeline config              │
│ 7. Deploy pipeline     → debug issues                       │
│ 8. Documentation       → write from scratch                 │
│                                                              │
│ Time: 2-5 days                                              │
│ Result: May miss best practices                             │
└─────────────────────────────────────────────────────────────┘
```

## Designing Golden Paths

### Identifying Candidates

```text
Golden Path Selection Criteria:

High-Value Candidates:
├── Frequent: Done by many teams regularly
├── Complex: Easy to get wrong
├── Critical: Security/compliance implications
├── Costly: Takes significant time manually
└── Standardizable: Common pattern across teams

Assessment Matrix:
┌────────────────────────────────────────────────────────────┐
│               Frequency                                     │
│            Low          High                                │
│         ┌─────────────┬─────────────┐                      │
│  High   │ Custom      │ GOLDEN PATH │ ← High Impact        │
│         │ Solution    │ PRIORITY    │                      │
│ Impact  ├─────────────┼─────────────┤                      │
│  Low    │ Ignore      │ Document/   │                      │
│         │             │ Automate    │                      │
│         └─────────────┴─────────────┘                      │
└────────────────────────────────────────────────────────────┘

Common Golden Paths:
1. New service creation (by service type)
2. Database provisioning
3. CI/CD pipeline setup
4. Security scanning integration
5. Observability setup
6. Environment creation
7. API development workflow
8. Frontend application setup
```

### Template Design Principles

```text
Template Design:

1. Opinionated Defaults
   ├── Make decisions so developers don't have to
   ├── Choose proven technologies
   ├── Use sensible configurations
   └── Document why choices were made

2. Minimal Required Input
   ├── Service name
   ├── Team/owner
   ├── 1-3 key configuration choices
   └── Everything else has defaults

3. Complete Package
   ┌─────────────────────────────────────────────────────────┐
   │ Template Contents:                                       │
   │                                                          │
   │ Application Layer:                                       │
   │ ├── Application code skeleton                            │
   │ ├── Configuration management                             │
   │ ├── Health check endpoints                               │
   │ └── API documentation setup                              │
   │                                                          │
   │ Quality Layer:                                           │
   │ ├── Unit test framework                                  │
   │ ├── Integration test setup                               │
   │ ├── Linting and formatting                               │
   │ └── Pre-commit hooks                                     │
   │                                                          │
   │ Operations Layer:                                        │
   │ ├── Dockerfile                                           │
   │ ├── Kubernetes manifests                                 │
   │ ├── CI/CD pipeline                                       │
   │ └── Infrastructure as Code                               │
   │                                                          │
   │ Observability Layer:                                     │
   │ ├── Structured logging                                   │
   │ ├── Metrics instrumentation                              │
   │ ├── Distributed tracing                                  │
   │ └── Dashboard templates                                  │
   │                                                          │
   │ Documentation Layer:                                     │
   │ ├── README template                                      │
   │ ├── ADR templates                                        │
   │ ├── Runbook templates                                    │
   │ └── API specification                                    │
   └─────────────────────────────────────────────────────────┘

4. Clear Extension Points
   ├── Where to add business logic
   ├── How to add new endpoints
   ├── How to integrate dependencies
   └── How to customize behavior
```

### Template Architecture

```text
Template Implementation Patterns:

1. Scaffolding/Generation (Backstage, Yeoman)
   Input → Template + Variables → Generated Repo

   Pros: Simple, full control
   Cons: Generated