Stage Gate Workflow - Quick Reference

Author

Sarfaraz Mulla

Published

December 28, 2025

1 Overview

Version: 1.0 Last Updated: 2025-12-28

This workflow defines an 8-phase progressive elaboration framework for software development with Claude Code.

2 The 8 Phases

Phase 1: Business Context & Requirements
    ↓ Gate: User approves requirements
Phase 2: Technical Architecture
    ↓ Gate: User approves architecture
Phase 3: Solution Design (Tech Stack)
    ↓ Gate: User approves technology choices
Phase 4: Detailed Design
    ↓ Gate: User approves implementation plan
Phase 5: Implementation
    ↓ Gate: Code works locally
Phase 6: Testing & Validation
    ↓ Gate: All tests pass
Phase 7: Deployment
    ↓ Gate: Production deployment successful
Phase 8: Post-Deployment
    ↓ Iterate: Return to Phase 1 for improvements

3 Key Principles

  1. Phase Gates - User approves before moving to next phase
  2. Question First, Code Later - Understand before implementing
  3. Justify Tech Choices - Always explain “why X instead of Y?”
  4. Progressive Elaboration - Each phase adds more detail
  5. Branching Allowed - Can revisit earlier phases if new info emerges
  6. Documentation as You Go - Update plan file at each phase
  7. User Involvement - Regular checkpoints prevent misalignment

4 When to Use This Workflow

4.1 ✅ Use for:

  • New features (non-trivial)
  • Architecture changes
  • Technology stack decisions
  • Multi-file changes
  • Unclear requirements

4.2 ❌ Skip for:

  • Typo fixes
  • Single-line changes
  • Trivial updates
  • Well-defined simple tasks

5 Phase 1: Business Context (Start Here)

Ask these questions FIRST before coding:

  1. Business Problem: What problem are we solving?
  2. User Persona: Who will use this?
  3. Success Criteria: How do we measure success?
  4. Constraints: What are the non-negotiables?

Gate: User confirms understanding → Proceed to Phase 2

6 Phase 3: Tech Stack (Critical Phase)

Before choosing any technology, answer:

  1. Why this tool over alternatives?
  2. What can we remove/simplify?
  3. How does it fit existing stack?

Gate: User approves tech choices → Proceed to Phase 4

7 Example Usage

# New Feature: Add User Authentication

## Phase 1: Business Context
**Business Problem**: Users can't securely access the system
**Users**: End users (100+ daily), admin users (5)
**Success Criteria**: 99.9% uptime, <500ms login time
**Constraints**: Must use company OAuth provider

**Gate Decision**: [x] Approved

## Phase 2: Technical Architecture
**Architecture Style**: Microservice (separate auth service)
**Integration Points**: Main app, admin dashboard
**Data Flow**: OAuth → Token → Session → Protected routes

**Gate Decision**: [x] Approved

## Phase 3: Solution Design
**Technology Choices**:
- Auth Provider: Company OAuth (required)
- Session Store: Redis (fast, scales horizontally)
- JWT Library: PyJWT (Python-native, secure)

**Why not alternatives?**:
- Not Flask-Login: Doesn't support OAuth well
- Not database sessions: Too slow for scale

**Gate Decision**: [x] Approved

[Continue through phases 4-8...]

8 Common Mistakes to Avoid

8.1 ❌ Don’t:

  • Jump to Phase 5 (Implementation) without Phases 1-4
  • Use technology X just because “it’s popular”
  • Skip gate approvals
  • Trust stale documentation without verification
  • Perpetuate inherited patterns without questioning

8.2 ✅ Do:

  • Ask “why” questions early
  • Get user approval at each gate
  • Document decisions as you go
  • Question tool choices
  • Verify claims and metrics

9 Real-World Example

Data Validator Project (documented in full workflow):

9.1 What Went Wrong:

  • ❌ Used pandas without questioning
  • ❌ Perpetuated NaN serialization issues
  • ❌ Didn’t verify “60+ rules” claim (actually 41)

9.2 What Went Right (after applying workflow):

  • ✅ User questioned tech choices (“why pandas?”)
  • ✅ Re-evaluated architecture (DuckDB vs pandas)
  • ✅ Got approval before proceeding
  • ✅ Verified metrics
  • ✅ Designed for microservice extraction

Lesson: Following the workflow prevented costly rework

10 How to Apply This Workflow

10.1 For New Tasks:

  1. Don’t code immediately - Start with Phase 1 questions
  2. Document in plan file - Use template from full doc
  3. Get gate approval - Wait for user confirmation at each phase
  4. Question everything - “Why X instead of Y?”
  5. Branch back if needed - New info? Revisit earlier phase

10.2 For Claude Code Users:

When prompting Claude Code for new features, use this structure:

Task: [Describe feature]

Please follow Stage Gate Workflow:

Phase 1: Ask business context questions
Phase 2: Propose architecture, wait for approval
Phase 3: Justify tech stack choices, wait for approval
Phase 4: Show detailed design, wait for approval
Phase 5: Implement only after gates 1-4 pass

Workflow reference: stage-gate-workflow-full.qmd

11 Quick Tips

💡 Most Common Mistake: Jumping to Phase 5 (Implementation) without Phases 1-4

💡 Most Important Phase: Phase 3 (Tech Stack) - prevents wrong tool choices

💡 Most Skipped Gate: Phase 2 gate - leads to architecture misalignment

💡 Best Practice: Write plan file FIRST, code SECOND

12 Need Help?

Can I skip phases? Only for trivial tasks (typos, single-line fixes)

What if I discover new info mid-implementation? Branch back to earlier phase (e.g., Phase 5 → Phase 3 if tech choice wrong)

Remember: This workflow exists to prevent costly rework. 10 minutes of planning saves 10 hours of coding the wrong solution.

For full details, see: Full Workflow Documentation