PLAT-02] Define and document the golden path for Goald feature development

[paruff]

[PLAT-02] Define and document the golden path for Goald feature development

GitHub Issue Title: [PLAT-02] Define and document the golden path for Goald feature development

Field	Value
Phase	Phase 4 — Quality Flywheel
DORA 2025 Source	DORA 2025 Platform Engineering capability: “Identify the golden path for the most common workflow and build just enough to make that specific journey demonstrably better”; “Shift down cognitive load — developers focus on delivering user value, not navigating infrastructure”; “Developer independence resulted in 5% productivity improvement”
Labels	devops, documentation, ai-ops, p2-important, effort-small
Effort	Small (< 1 day)
Assignee	👤 Human
Prerequisites	ARCH-01, AIOPS-01, DEVOPS-01, PLAT-01

---

Why DORA 2025 Introduces This as a Specific Requirement

The 2025 DORA Platform Engineering capability page introduces a concept that reframes how small teams should think about their tooling: the golden path.

“Identify the golden path for the most common workflow and build just enough to make that specific journey demonstrably better.”

The golden path is not a comprehensive platform. It is the single, documented, lowest-friction route from idea to deployed feature. DORA research found that developer independence — the ability to complete a task without relying on external help, documentation hunting, or tribal knowledge — produced a 5% improvement in individual and team productivity.

For a vibe-coding workflow, the golden path is especially important because Copilot follows the path it sees. If the path is unclear, Copilot creates inconsistent patterns. If the path is clearly documented and enforced, Copilot follows it reliably.

---

The Goald Golden Path: Idea → Production

The golden path for a standard feature in Goald is:

1. SPEC          Create a GitHub issue using the [feature] template (AIOPS-03)
                 Write acceptance criteria and one BDD scenario
                 
2. BRANCH        git checkout -b feat/ISSUE-ID-short-description
                 
3. TEST FIRST    Write the failing test (unit or E2E scenario)
                 Commit: test(scope): failing test for [ISSUE-ID]
                 
4. IMPLEMENT     Prompt Copilot with the acceptance criteria + failing test
                 Use the relevant prompt template from PROMPT_LIBRARY.md (AIOPS-04)
                 
5. VERIFY        npm test → must pass
                 npm run lint → must pass
                 npm run typecheck → must pass
                 
6. PR             git push, open PR with AI-Assisted Review Block completed (REVIEW-01)
                 Reference issue: "Closes #N"
                 
7. CI GATE       GitHub Actions runs lint + typecheck + tests
                 PR cannot merge if CI fails
                 
8. REVIEW        Human reviews against GITOPS-04 checklist (< 24h target)
                 
9. MERGE         Squash merge to main with conventional commit message
                 
10. DEPLOY        Expo OTA publishes automatically on merge to main (DEVOPS-02)
                  Sentry release marker created

---

Acceptance Criteria

The Golden Path Document

• docs/GOLDEN_PATH.md created with:
  • The 10-step path above, tailored to the current state of Goald’s tooling
  • The exact commands for each step (copy-paste ready)
  • The Copilot prompt strategy for step 4 (links to PROMPT_LIBRARY.md)
  • Common failure points and how to recover from each
  • “Off-path” decisions that require human judgment (architecture changes, security-sensitive code, legal/compliance features)

Cognitive Load Reduction (DORA “shift down” recommendation)

• Every step in the golden path has a corresponding npm script or one-liner command that a developer can run without memorising flags:

  "scripts": {
    "new-feature": "echo 'See docs/GOLDEN_PATH.md'",
    "preflight": "npm run lint && npm run typecheck && npm test",
    "pr-ready": "npm run preflight && echo '✅ Ready to push'",
    "metrics": "bash scripts/weekly-metrics.sh"
  }

• npm run preflight works and is documented as “run this before every push”

• npm run pr-ready works and is documented as “run this before opening a PR”

First-Feature Walkthrough

• A real issue from the backlog (effort-small, Phase 3 or 4) is completed following the golden path exactly, with notes in the PR about where the path was clear and where it had friction
• Any friction points identified in that walkthrough are documented as follow-up issues

---

Files to Create / Change

• docs/GOLDEN_PATH.md (create)
• package.json — add preflight and pr-ready scripts
• README.md — add “Development Workflow” section linking to docs/GOLDEN_PATH.md
• .github/copilot-instructions.md — add one-line reference: “See docs/GOLDEN_PATH.md for the standard feature development workflow”