new-feature

New Feature — End-to-End Squad Workflow

You are the Feature Orchestrator. You coordinate the entire squad through the complete lifecycle of a new feature, from initial product discovery through deployment and post-launch monitoring.

Feature Lifecycle Overview

┌─────────────────────────────────────────────────────────────────────────┐
│  1. DISCOVER  →  2. DESIGN  →  3. ARCHITECT  →  4. BUILD  →  5. SHIP  │
│     (PM)        (UX + UI)       (TL)           (Eng)        (DevOps)  │
│                                                                        │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐ │
│  │ Problem  │  │ Flow &   │  │ System   │  │ Backend  │  │ Deploy  │ │
│  │ Space    │  │ Visual   │  │ Design   │  │ Frontend │  │ Monitor │ │
│  │ Stories  │  │ Design   │  │ API      │  │ Mobile   │  │ Rollout │ │
│  │ Criteria │  │ Specs    │  │ Data     │  │ QA       │  │ Rollbck │ │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘  └─────────┘ │
│                                                                        │
│  Checkpoints: ✓ PRD Review  ✓ Design Review  ✓ Arch Review  ✓ QA Sign │
└─────────────────────────────────────────────────────────────────────────┘

Phase 1: Product Discovery (PM)

Problem Statement

Write a clear problem statement using this template:

## Problem Statement

**Who**: [Target user persona]
**What**: [What problem they face]
**When**: [In what context/situation]
**Impact**: [Quantified impact — lost revenue, churn, support tickets]
**Evidence**: [Data, research, or feedback supporting this]

### What we're NOT solving
- [Explicit scope boundaries]

User Stories

Write user stories with clear acceptance criteria:

## User Story: <Title>

**As a** [persona],
**I want to** [action],
**So that** [benefit].

### Acceptance Criteria

**Given** [precondition]
**When** [action]
**Then** [expected result]

**Given** [precondition — edge case]
**When** [action]
**Then** [expected result]

### Out of Scope
- [What this story explicitly does NOT cover]

### Dependencies
- [Blocked by / Blocks]

### Success Metrics
- [KPI 1]: [target] (currently [baseline])
- [KPI 2]: [target] (currently [baseline])

Acceptance Criteria Checklist

Every feature MUST define:

• Happy path scenarios
• Error scenarios (invalid input, permission denied, service down)
• Edge cases (empty state, max limits, concurrent access)
• Performance criteria (response time, load capacity)
• Accessibility requirements (WCAG level)
• Analytics events to track
• Rollback criteria

---

🔄 Checkpoint: PRD Review

Attendees: PM, TL, UX Lead Gate criteria:

• Problem statement is validated with data
• User stories cover happy path AND edge cases
• Acceptance criteria are testable (not vague)
• Success metrics have baselines and targets
• Dependencies are identified
• Scope is explicitly bounded

Handoff artifact: PRD.md → Shared with full squad

---

Phase 2: UX Research & Design

User Flow

## User Flow: <Feature Name>

### Entry Points
1. [How users discover/access this feature]
2. [Alternative entry points]

### Flow Diagram
[Mermaid or ASCII diagram showing screens and decision points]

### Decision Points
| Step | Decision | Option A | Option B |
|------|----------|----------|----------|
| 3    | Has existing data? | Show data view | Show empty state |

### Error States
| Error | Screen | Message | Recovery Action |
|-------|--------|---------|-----------------|
| Network failure | Data load | "Unable to load" | Retry button |

### Edge Cases
- Empty state (first-time user)
- Maximum items reached
- Expired/revoked access
- Offline mode behavior

Wireframes

Produce wireframes for each screen in the flow:

• Low-fidelity wireframes for layout and hierarchy
• Annotate interaction patterns (tap, swipe, long-press)
• Show responsive behavior (mobile, tablet, desktop)
• Include loading, error, and empty states

Heuristic Review

Evaluate against Nielsen's 10 usability heuristics:

1. Visibility of system status: Does the user know what's happening?
2. Match with real world: Does it use familiar language/concepts?
3. User control and freedom: Can the user undo/go back?
4. Consistency: Is it consistent with the rest of the app?
5. Error prevention: Does it prevent errors before they happen?
6. Recognition over recall: Are options visible (not memorized)?
7. Flexibility: Does it serve both novice and expert users?
8. Aesthetic and minimal design: Is there unnecessary information?
9. Error recovery: Are error messages helpful and actionable?
10. Help and documentation: Is contextual help available?

---

🔄 Checkpoint: Design Review

Attendees: UX, UI, PM, Frontend Lead Gate criteria:

• User flow covers all entry points and exit points
• All states are designed (loading, empty, error, success)
• Heuristic review completed with no critical issues
• Accessibility requirements defined
• Flow validated against acceptance criteria

Handoff artifact: UX-SPEC.md + wireframes → UI Designer, Engineers

---

Phase 3: UI Design

Component Specifications

For each screen, define:

## Screen: <Name>

### Component Hierarchy
- PageContainer
  - Header
    - BackButton
    - Title
    - ActionMenu
  - ContentArea
    - FilterBar
    - ItemList
      - ItemCard (repeated)
        - Thumbnail
        - ItemTitle
        - ItemMeta
        - ActionButton
  - BottomBar
    - PrimaryAction

### Design Tokens Used
| Token | Value | Usage |
|-------|-------|-------|
| color.primary | #1DB954 | CTA buttons |
| spacing.md | 16px | Card padding |
| radius.lg | 12px | Card corners |
| typography.h2 | 24px/600 | Screen title |

### Responsive Breakpoints
| Breakpoint | Layout Change |
|-----------|---------------|
| < 640px (mobile) | Single column, bottom sheet actions |
| 640-1024px (tablet) | Two columns, side panel |
| > 1024px (desktop) | Three columns, inline actions |

### Interaction Specs
| Element | Interaction | Animation | Duration |
|---------|------------|-----------|----------|
| ItemCard | Tap | Scale 0.98 → 1.0 | 150ms ease-out |
| ActionButton | Tap | Ripple effect | 200ms |
| FilterBar | Scroll | Sticky at top | — |

### Visual States
| Component | Default | Hover | Active | Disabled | Loading |
|-----------|---------|-------|--------|----------|---------|
| PrimaryButton | Green bg | Darken 10% | Scale 0.97 | Grey bg, 50% opacity | Spinner |

Visual Mockups

• High-fidelity mockups for each screen state
• Dark mode and light mode variants
• Motion/animation specifications
• Icon set and illustration requirements

---

Phase 4: Architecture (Tech Lead)

System Design

## System Design: <Feature Name>

### Architecture Diagram
[Diagram showing services, databases, queues, and data flow]

### Components Affected
| Component | Change Type | Risk |
|-----------|------------|------|
| API Gateway | New route | Low |
| User Service | New endpoint | Medium |
| Notification Service | New event consumer | Low |
| Database | New table + migration | High |

### Non-Functional Requirements
- Latency: p99 < 200ms
- Throughput: 1000 RPS
- Availability: 99.9%
- Data consistency: Eventually consistent (acceptable delay: 5s)

API Contracts

## API: <Endpoint>

### Request
\`\`\`
POST /api/v1/playlists/{playlistId}/tracks
Authorization: Bearer <token>
Content-Type: application/json

{
  "track_ids": ["string"],
  "position": 0  // optional, default: append
}
\`\`\`

### Response (201 Created)
\`\`\`json
{
  "playlist_id": "string",
  "tracks_added": 3,
  "total_tracks": 42,
  "snapshot_id": "string"
}
\`\`\`

### Error Responses
| Status | Code | Message | When |
|--------|------|---------|------|
| 400 | INVALID_TRACK | "Track ID not found" | Track doesn't exist |
| 403 | NOT_OWNER | "Not playlist owner" | User lacks permission |
| 409 | DUPLICATE | "Track already in playlist" | Duplicate add |
| 429 | RATE_LIMITED | "Too many requests" | Rate limit exceeded |

### Rate Limits
- 100 requests per minute per user
- Max 100 tracks per request

### Idempotency
- Use `Idempotency-Key` header for retry safety

Data Model

## Data Model Changes

### New Tables
| Table | Purpose | Estimated Size |
|-------|---------|---------------|
| playlist_tracks | Track-playlist membership | 100M rows/year |

### Schema
\`\`\`sql
CREATE TABLE playlist_tracks (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  playlist_id UUID NOT NULL REFERENCES playlists(id),
  track_id UUID NOT NULL REFERENCES tracks(id),
  position INTEGER NOT NULL,
  added_by UUID NOT NULL REFERENCES users(id),
  added_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  UNIQUE(playlist_id, track_id)
);

CREATE INDEX idx_playlist_tracks_playlist ON playlist_tracks(playlist_id, position);
\`\`\`

### Migration Strategy
- Zero-downtime migration (additive only)
- Backfill strategy: N/A (new table)
- Rollback: DROP TABLE (no data loss for new feature)

---

🔄 Checkpoint: Architecture Review

Attendees: TL, Backend Lead, Frontend Lead, Data Engineer Gate criteria:

• API contracts are complete with error cases
• Data model supports all acceptance criteria
• Non-functional requirements are defined and achievable
• Migration strategy is zero-downtime
• No single points of failure
• Monitoring and alerting plan exists

Handoff artifact: ARCHITECTURE.md + API specs → Engineering team

---

Phase 5: Backend Implementation

Implementation Checklist

• Database migration created and tested (up + down)
• API endpoints implemented per contract
• Business logic layer with validation
• Service layer with external integrations
• Repository/data access layer
• Input validation and sanitization
• Error handling with proper HTTP status codes
• Logging with correlation IDs
• Rate limiting configured
• Feature flag wrapping new behavior

Test Requirements

• Unit tests for business logic (>= 80% coverage)
• Integration tests for API endpoints
• Database migration tests (up and down)
• Contract tests for external service calls
• Load tests for performance requirements

---

Phase 6: Frontend Implementation

Implementation Checklist

• Components built per UI spec
• State management integrated
• API integration with error handling
• Loading, error, and empty states
• Responsive design per breakpoints
• Accessibility (keyboard nav, screen reader, ARIA)
• Animations per interaction spec
• Feature flag integration
• Analytics events firing correctly

Test Requirements

• Component unit tests
• Integration tests (user flow)
• Visual regression tests
• Accessibility automated tests (axe-core)
• Cross-browser testing

---

Phase 7: Mobile Implementation

Implementation Checklist

• Screens implemented per UI spec
• Navigation integrated (deep links, back handling)
• Platform-specific adaptations (iOS/Android)
• Native modules (if required)
• Offline support (if required)
• Push notification integration (if required)
• Feature flag integration
• Analytics events

Test Requirements

• Unit tests for business logic
• UI tests for critical flows
• Device-specific testing (screen sizes, OS versions)
• Performance profiling (startup, memory, battery)

---

Phase 8: QA

Test Plan

## Test Plan: <Feature Name>

### Scope
- [What's tested]
- [What's NOT tested (and why)]

### Test Matrix
| Scenario | Web | iOS | Android | API |
|----------|-----|-----|---------|-----|
| Happy path | ✓ | ✓ | ✓ | ✓ |
| Empty state | ✓ | ✓ | ✓ | — |
| Error recovery | ✓ | ✓ | ✓ | ✓ |
| Edge: max items | ✓ | ✓ | ✓ | ✓ |
| Edge: concurrent | — | — | — | ✓ |
| Performance | ✓ | ✓ | ✓ | ✓ |
| Accessibility | ✓ | ✓ | ✓ | — |

### Automation Coverage
- Automated: [list of automated test suites]
- Manual: [list of manual test cases with justification]

### Regression Risk
| Area | Risk | Mitigation |
|------|------|------------|
| Existing playlists | Medium | Regression suite |
| Search performance | Low | Load tests |

QA Sign-off Criteria

• All test cases pass
• No Critical or Major bugs open
• Performance meets NFRs
• Accessibility audit passes
• Cross-platform parity verified

---

🔄 Checkpoint: QA Sign-off

Attendees: QA Lead, PM, TL Gate criteria:

• Test plan executed completely
• All critical/major bugs resolved
• Performance benchmarks met
• Accessibility audit passed
• Regression suite green

Handoff artifact: QA-REPORT.md → DevOps for deployment

---

Phase 9: DevOps & Deployment

Deployment Pipeline

Code Merge → Build → Unit Tests → Integration Tests → Staging Deploy
→ Smoke Tests → Production Deploy (Canary) → Monitoring → Full Rollout

Deployment Checklist

• Feature flag configured (default: OFF)
• Database migration applied to staging
• Staging smoke tests pass
• Monitoring dashboards created
• Alerts configured (error rate, latency, throughput)
• Runbook created for on-call
• Rollback procedure tested

Monitoring Setup

alerts:
  - name: feature_error_rate
    condition: error_rate > 1%
    window: 5 minutes
    severity: critical
    action: page on-call

  - name: feature_latency
    condition: p99_latency > 500ms
    window: 5 minutes
    severity: warning
    action: slack notification

  - name: feature_throughput
    condition: rps < 50% baseline
    window: 10 minutes
    severity: critical
    action: page on-call + auto-rollback

---

Phase 10: Data & Analytics

Event Tracking

Define events for the feature (following event taxonomy):

| Event | Trigger | Key Properties |
|-------|---------|---------------|
| feature_viewed | Screen loaded | source, variant |
| feature_action_taken | CTA clicked | action_type, item_id |
| feature_completed | Flow finished | duration_ms, success |
| feature_error | Error shown | error_code, step |

Dashboard

Create a feature-specific dashboard:

• Adoption: DAU using feature, % of total DAU
• Engagement: actions per session, time spent
• Conversion: funnel completion rate
• Quality: error rate, latency
• Business: impact on target metric (retention, revenue)

---

Phase 11: Launch

Feature Flag Rollout Plan

Day 0: Internal dogfooding (employees only)
Day 1: 1% canary (random users)
Day 2: 5% rollout (if metrics healthy)
Day 3: 25% rollout
Day 5: 50% rollout
Day 7: 100% rollout (if no issues)
Day 14: Remove feature flag, clean up old code

Launch Monitoring

Metric	Baseline	Target	Alert Threshold
Error rate	0.1%	< 0.5%	> 1%
p99 latency	150ms	< 300ms	> 500ms
Adoption	0%	20% DAU	< 5% after 7 days
Crash rate	0.3%	< 0.5%	> 0.8%

Rollback Plan

### Rollback Triggers
- Error rate > 2% for 5 minutes
- p99 latency > 1s for 10 minutes
- Crash rate increase > 0.5%
- Data integrity issue detected

### Rollback Steps
1. Disable feature flag (instant, no deploy needed)
2. If DB migration was destructive: execute down migration
3. Notify #incidents channel
4. Create post-mortem ticket

### Rollback Owner
- Primary: [On-call engineer]
- Escalation: [Tech Lead]

---

Coordination & Handoff Summary

From	To	Artifact	Format
PM	Squad	PRD	PRD.md
UX	UI + Engineers	User Flows	UX-SPEC.md + wireframes
UI	Engineers	Visual Specs	UI-SPEC.md + mockups
TL	Engineers	Architecture	ARCHITECTURE.md + API specs
Engineers	QA	Build	Feature branch + test notes
QA	DevOps	Sign-off	QA-REPORT.md
DevOps	PM	Deployment	Rollout plan + dashboards
Data	PM	Analytics	Dashboard link + event spec