/learn-technical-design

name: Learn why to discuss technical design before implementation
description: Interactive guidance on creating technical design PRs to align with your team before coding.
user-invocable: false

Why Discuss Technical Design Before Implementation?

Overview

This learning module helps junior developers understand why creating a technical design PR before implementation leads to better outcomes, faster delivery, and reduced rework.

Instructions

Present the following content interactively. After each section, use `AskUserQuestion` to offer 3 options:

• "Continue to next section"
• "Show me an example"
• "I have a question"

---

Section 1: The Purpose of Technical Design PRs

Explain that in story-flow, before writing implementation code, developers create a pull request containing their technical design:

**A technical design PR serves three purposes:**

1. **Early feedback on approach** - Get team input before investing time in implementation 2. **Alignment before coding** - Ensure everyone agrees on the direction 3. **Living documentation** - The merged design becomes part of the repo history

**The key insight:**

> A technical design PR is not about seeking permission. It's about leveraging collective expertise to find the best solution before committing to an approach.

**What gets included:**

• Story requirements (from the story tracker, Figma analysis)
• Planned tasks with execution order
• Pseudo code, example payloads, or expected API responses
• Questions or concerns for reviewers

---

Section 2: The Shift-Left Concept

Explain the "shift-left" principle:

**Shift-left** means moving quality activities earlier in the development lifecycle.

Traditional approach (problems found late):

Design → Code → Code Review → QA → Production
                              ↑
                     Problems found here
                     (expensive to fix)

Shift-left approach (problems found early):

Design Review → Code → Code Review → QA → Production
      ↑
Problems found here
(cheap to fix)

**Why "left"?**

If you imagine the development timeline flowing left-to-right, shifting activities to the left means doing them earlier.

**The cost curve:**

| Stage Where Issue Found | Relative Cost to Fix | |------------------------|---------------------| | Design review | 1x | | Code review | 5x | | QA testing | 10x | | Production | 100x |

Issues found later require:

• Undoing completed work
• Retesting affected areas
• Potential customer impact
• Emergency context-switching

---

Section 3: Cost-Effectiveness Benefits

Present the concrete benefits:

1. Avoid Wasted Implementation Effort

Without design review:

Developer spends 3 days implementing Feature X
  → Code review reveals a simpler approach exists
  → 3 days of work discarded
  → Rework begins

With design review:

Developer spends 2 hours writing design PR
  → Team suggests simpler approach
  → 2 hours adjusted
  → Implementation proceeds correctly

2. Reduce Rework Cycles

| Approach | Typical Iterations | |----------|-------------------| | Code first, discuss later | 3-5 review cycles | | Design first, code second | 1-2 review cycles |

3. Faster Overall Delivery

**Paradox:** Adding a "planning step" actually speeds up delivery.

Without planning:   [3 days coding] + [2 days rework] = 5 days
With planning:      [2 hours design] + [2 days coding] = 2.25 days

4. Knowledge Sharing

Design PRs help the team:

• Understand upcoming changes
• Suggest improvements from past experience
• Identify conflicts with parallel work
• Onboard new team members through design history

---

Section 4: What to Include in a Technical Design PR

Present the recommended structure:

In the Story Markdown File

**1. Story Requirements**

• Acceptance criteria from the story tracker
• Insights from Figma designs
• Business context and user impact

**2. Planned Tasks**

• Ordered list of implementation steps
• Dependencies between tasks
• Which tasks can run in parallel
• Each task includes technical approach details:
• Key design decisions
• Pseudo code for complex logic
• Example payloads or API contracts

// Example task with embedded technical approach:
// Task: Add user authentication endpoint @src/api/auth.ts
// - Use JWT tokens with 24h expiry
// - Store refresh tokens in httpOnly cookies
//
// Expected API response:
interface LoginResponse {
  accessToken: string;
  expiresIn: number;
  user: {
    id: string;
    email: string;
  };
}

In the Pull Request

**3. Alternatives Considered** *(include in PR description or comments)*

| Approach | Pros | Cons | Decision | |----------|------|------|----------| | Option A | Fast to implement | Hard to extend | | | Option B | Flexible | More complex | Chosen |

**4. Questions for Reviewers** *(include in PR description or comments)*

• Highlight uncertainties
• Ask for input on specific decisions
• Flag areas where you need guidance

---

Section 5: Common Mistakes to Avoid

Present each mistake with correction:

Mistake 1: Skipping Design for "Simple" Changes

"This is just a small feature, I'll skip the design PR"
  → Feature has hidden complexity
  → Major rework needed after code review

**Better approach:** Start with a lightweight design. If it's truly simple, the design takes 15 minutes and confirms that.

Mistake 2: Not Enough Implementation Detail

# BAD - Too vague
## Tasks
- Add authentication
- Update UI

# GOOD - Actionable detail
## Tasks
1. Create AuthService class with login/logout methods
2. Add JWT token storage in localStorage
3. Create ProtectedRoute component wrapper
4. Update Header to show user email when logged in

Mistake 3: Treating Design as Final

"The design is approved, I can't change anything now"

**Reality:** Designs evolve during implementation. When you discover something that changes the approach: 1.