How to: Plan and Execute Features Using the Scrum/ZenHub Workflow

Overview

This guide walks through the complete lifecycle of planning and executing features in the SyRF project, integrating the documentation framework with Scrum practices and ZenHub execution tracking.

When to use this workflow: Planning any new feature or significant enhancement that requires team coordination and sprint-based execution.

Prerequisites

• Familiarity with Documentation Framework
• Access to ZenHub (for execution phase)
• Understanding of Scrum terminology (Project → Epic → Feature → Story)

Workflow Phases

Phase 1: Planning (Markdown)
    ↓
Phase 2: Transfer to ZenHub (Execution)
    ↓
Phase 3: Sprint Execution (ZenHub tracks progress)
    ↓
Phase 4: Completion & Documentation (Markdown)

---

Phase 1: Planning (Markdown)

Goal: Document feature requirements, design, and implementation plan using markdown for rapid iteration and LLM collaboration.

Step 1.1: Create Feature Directory

mkdir -p docs/features/{feature-name}
cd docs/features/{feature-name}

Naming Convention: Use kebab-case (e.g., user-authentication, data-export-v2, api-rate-limiting)

Step 1.2: Create Feature Brief

Create README.md using the Feature Brief template from /docs/README.md#feature-brief-template.

Key fields to set:

---
doc-type: "Feature"
status: "Draft"
priority: "Medium"  # Low|Medium|High|Critical
zenhub-ticket: "TBD"  # Will be updated when Epic is created
---

Essential sections:

• Executive Summary: 2-3 sentence overview
• Problem Statement: What problem does this solve?
• Proposed Solution: High-level approach
• User Stories: As a [user], I want [capability] so that [benefit]
• Success Criteria: Measurable outcomes
• Out of Scope: What will NOT be addressed
• MVP vs Future Phases: What ships first vs later

Step 1.3: Gather Requirements (Optional Q&A)

For complex features, create a Q&A file to gather clarifications:

vi docs/planning/{feature-name}-qa.md

Use checkboxes for options and leave space for free-text notes. Delete this file once requirements are incorporated into the Feature Brief.

Step 1.4: Update Feature Brief Status

status: "In-Review"

Share with team for feedback. Iterate until consensus is reached.

status: "Approved"

Step 1.5: Create Technical Plan

Create technical-plan.md in the same directory using the Technical Plan template.

Key sections:

• Architecture Overview: System design, component interaction
• Implementation Approach: Step-by-step strategy
• API Design: Endpoints, contracts, data models
• Database Schema: Tables, indexes, relationships
• Developer Checklist: Break down into specific tasks with story point estimates

Example Developer Checklist:

## Developer Checklist

### Backend Tasks
- [ ] Create User model and migration (2 points)
- [ ] Implement authentication service (5 points)
- [ ] Add login/logout endpoints (3 points)
- [ ] Write unit tests for auth service (2 points)
- [ ] Add integration tests (3 points)

### Frontend Tasks
- [ ] Create login form component (3 points)
- [ ] Implement auth state management (2 points)
- [ ] Connect to auth API (2 points)
- [ ] Add form validation (1 point)
- [ ] Write component tests (2 points)

**Total Estimated**: 25 points

Step 1.6: Estimate and Plan Phases

Review total story points with team. If > 13 points (2 sprint max), break into MVP and future phases:

## Implementation Phases

### Phase 1: MVP (Sprint 1, 13 points)
- Core authentication (login/logout)
- Session management
- Basic security

### Phase 2: Enhanced Features (Sprint 2, 12 points)
- Password reset
- Email verification
- Two-factor authentication

Update both documents:

status: "Approved"
zenhub-ticket: "TBD"  # Still TBD until created in ZenHub

---

Phase 2: Transfer to ZenHub (Execution)

Goal: Create Epic and Stories in ZenHub, establishing it as the source of truth for execution tracking.

Step 2.1: Create Epic in ZenHub

1. Go to ZenHub board for the repository
2. Click "New Issue" → "Epic"
3. Title: Match Feature Brief title (e.g., "User Authentication System")
4. Description:

## Epic: User Authentication System

See feature documentation: `/docs/features/user-authentication/`

## Goal
[Copy executive summary from Feature Brief]

## Success Criteria
[Copy from Feature Brief]

## Phases
- Phase 1: MVP (Sprint 1, 13 points)
- Phase 2: Enhanced (Sprint 2, 12 points)

1. Labels: Add epic, feature, priority label
2. Estimate: Total story points (e.g., 25 points)
3. Note the Epic number (e.g., #456)

Step 2.2: Create Stories from Technical Plan

For each task in the developer checklist:

1. Create new Issue in ZenHub
2. Title: Match task description
3. Description:

Part of Epic #456: User Authentication System

## Task
[Detailed description]

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Technical Notes
[Any implementation details]

## Related Docs
`/docs/features/user-authentication/technical-plan.md`

1. Link to Epic: Use ZenHub "Connect to Epic" feature
2. Estimate: Story points from technical plan
3. Labels: Add appropriate labels (backend/frontend, component)
4. Milestone: Assign to sprint milestone if already scheduled

Repeat for all tasks in Phase 1 MVP.

Step 2.3: Update Documentation with Epic Link

Update both Feature Brief and Technical Plan:

zenhub-ticket: "#456"  # Link to Epic
updated: 2025-11-05    # Today's date

Add to Feature Brief:

## ZenHub Tracking

- **Epic**: #456
- **Total Stories**: 8
- **Total Estimated Points**: 25
- **Phase 1 MVP**: 13 points (Sprint 1)
- **Phase 2 Enhanced**: 12 points (Sprint 2)

Step 2.4: Sprint Planning

During sprint planning meeting:

1. Review Epic #456 and all stories
2. Prioritize Phase 1 MVP stories
3. Add to sprint milestone
4. Move to "Sprint Backlog" pipeline in ZenHub
5. Assign stories to team members

Optional: Create sprint summary in /docs/planning/{project-name}/sprint-summary-YYYY-MM-DD.md

---

Phase 3: Sprint Execution (ZenHub)

Goal: Execute work using ZenHub as the source of truth for progress, tasks, and daily updates.

Daily Workflow

ZenHub is the source of truth during execution:

• Move cards through pipeline (To Do → In Progress → Review → Done)
• Update story descriptions with implementation notes
• Track blockers and dependencies
• Add comments on progress
• Adjust estimates if needed
• Create new stories for discovered work

Markdown stays stable during execution:

• Only update for major scope changes
• Only update for new architectural decisions (create ADR if significant)
• DO NOT track daily progress in markdown (use ZenHub)

When to Update Markdown During Sprint

DO update markdown if:

• MVP scope changes (document why in Feature Brief)
• New architectural decision made (create ADR in /docs/decisions/)
• Major technical approach changes (update Technical Plan)
• Dependency discovered that affects other features

DON'T update markdown for:

• Task completion (tracked in ZenHub)
• Story point adjustments (tracked in ZenHub)
• Implementation details (tracked in ZenHub story comments)
• Daily progress updates (tracked in ZenHub)

Sprint Review

At end of sprint:

1. Review completed stories in ZenHub
2. Note any scope changes or deferred work
3. Prepare for retrospective

---

Phase 4: Completion & Documentation (Markdown)

Goal: Update Feature Brief with final implementation summary, capturing divergence between planning and execution.

Step 4.1: Update Feature Brief with Implementation Summary

Add new section to Feature Brief:

## Implementation Summary

### Delivered (Sprint 1, Completed 2025-11-08)
- ✅ Core authentication (login/logout) - 8 points
- ✅ Session management - 3 points
- ✅ Basic security (password hashing, HTTPS) - 2 points

**Total Delivered**: 13 points

### Deferred to Phase 2
- 📋 Email verification - Deferred to Sprint 2
- 📋 Two-factor authentication - Deferred to Sprint 2

**Reason**: Focus on MVP to get core functionality to production faster.

### Scope Changes
- ✨ **Added**: JWT token refresh mechanism (not originally planned, 2 points)
  - **Reason**: Required for mobile app support discovered during implementation
- ❌ **Removed**: Remember me checkbox
  - **Reason**: Security team flagged as risk, deferred to Phase 2

### Original Plan vs Actual

#### Acceptance Criteria - Original (Planning)
- [ ] Users can login with email/password
- [ ] Users can logout
- [ ] Sessions persist across browser restarts
- [ ] Password requirements enforced (8+ chars, special chars)

#### Acceptance Criteria - Final (Delivered)
- ✅ Users can login with email/password
- ✅ Users can logout
- ✅ Sessions persist for 24 hours (changed from "across browser restarts")
- ✅ Password requirements enforced (12+ chars - increased from 8)
- ✅ JWT token refresh added (not in original plan)

### Lessons Learned
- Original estimate was accurate (13 points planned, 13 delivered)
- Token refresh should be planned upfront for future mobile features
- Security requirements should be reviewed earlier in planning phase

### Technical Decisions Made
- **ADR-NNN**: JWT vs Session-based Authentication (link to relevant ADR)
- **ADR-NNN**: Password Hashing with Argon2 (link to relevant ADR)

Step 4.2: Update Status and Metadata

If Phase 1 complete but Phase 2 remains:

status: "Approved"  # Keep as Approved, not Completed
updated: 2025-11-08

Add note:

## Status: Phase 1 Complete, Phase 2 Planned

Phase 1 MVP delivered in Sprint 1. Phase 2 (enhanced features) scheduled for Sprint 2.

If entire feature complete:

status: "Completed"
updated: 2025-11-08

Step 4.3: Archive Sprint Planning Docs

Delete temporary planning docs:

rm docs/planning/{feature-name}-qa.md  # If it exists
rm docs/planning/{project-name}/sprint-summary-YYYY-MM-DD.md  # If created

Keep permanent documentation:

• Feature Brief (with Implementation Summary)
• Technical Plan (as designed)
• ADRs (architectural decisions)

Step 4.4: Update Project README or Changelog

If appropriate, add entry to project changelog or service README:

## [1.2.0] - 2025-11-08

### Added
- User authentication system with login/logout (#456)
- JWT token refresh mechanism
- Session management with 24-hour expiration

### Security
- Password hashing using Argon2
- Minimum 12-character password requirement

---

Decision Matrices

When Should a Feature Get Documentation?

Scenario	Create Feature Brief?	Create Technical Plan?
Small bug fix (<2 points)	❌ No	❌ No
Medium enhancement (2-5 points)	🟡 Optional	❌ No
Large feature (5-13 points)	✅ Yes	✅ Yes
Epic-level feature (>13 points)	✅ Yes, with phases	✅ Yes, with phases
Architectural change	✅ Yes (or ADR)	✅ Yes

When to Update Markdown vs ZenHub

Information Type	Planning Phase	During Sprint	After Sprint
Requirements	Markdown (Feature Brief)	Stable in Markdown	Markdown (final summary)
Acceptance Criteria	Markdown (original)	ZenHub (current)	Markdown (final with divergence)
Task Breakdown	Markdown (initial estimate)	ZenHub (source of truth)	Markdown (if changed significantly)
Story Points	Markdown (estimates)	ZenHub (actual)	Markdown (summary)
Daily Progress	N/A	ZenHub only	Markdown (summary)
Architectural Decisions	Markdown (ADRs)	Markdown (ADRs if changed)	Markdown (permanent)
Scope Changes	N/A	ZenHub + Markdown (if major)	Markdown (document in summary)

Information Ownership

What Lives Where	Planning Phase	Execution Phase	Post-Completion
Original Design Intent	Markdown	Markdown (stable)	Markdown (archival)
Current Work Status	N/A	ZenHub	Markdown (summary)
Acceptance Criteria	Markdown	ZenHub (may diverge)	Markdown (both versions)
Task Lists	Markdown	ZenHub (source of truth)	Markdown (if useful)
Story Estimates	Markdown	ZenHub (may adjust)	Markdown (summary)
Blockers & Issues	N/A	ZenHub	Markdown (key learnings)
Architecture Decisions	Markdown (ADRs)	Markdown (update ADRs)	Markdown (permanent)

---

Examples

Example 1: Simple Feature (8 points, single sprint)

Feature: CSV Export for Study Data

1. ✅ Create Feature Brief: docs/features/csv-export/README.md with zenhub-ticket: "TBD"
2. ✅ Create Technical Plan: docs/features/csv-export/technical-plan.md with task breakdown
3. ✅ Create Epic #234 in ZenHub: "CSV Export for Study Data"
4. ✅ Create 4 stories from technical plan, link to Epic #234
5. ✅ Update both docs: zenhub-ticket: "#234"
6. 🔄 Sprint execution: ZenHub tracks progress
7. ✅ After completion: Update Feature Brief with implementation summary
8. ✅ Update status to Completed

Example 2: Large Feature with Phases (25 points, 2 sprints)

Feature: Advanced Search with Filters

1. ✅ Create Feature Brief with MVP and Phase 2 breakdown
2. ✅ Create Technical Plan with all tasks
3. ✅ Create Epic #456 in ZenHub: "Advanced Search System"
4. ✅ Create stories for Phase 1 MVP only (13 points)
5. ✅ Update docs: zenhub-ticket: "#456"
6. 🔄 Sprint 1 execution: Complete Phase 1 MVP
7. ✅ Update Feature Brief with Phase 1 summary, keep status: "Approved"
8. ✅ Create stories for Phase 2 (12 points)
9. 🔄 Sprint 2 execution: Complete Phase 2
10. ✅ Update Feature Brief with final summary
11. ✅ Update status to Completed

Example 3: Scope Change During Sprint

Feature: Data Export (Excel + CSV)

Original Plan (Feature Brief, 8 points):

• Export to Excel format (5 points)
• Export to CSV format (3 points)

During Sprint (Discovery):

• Excel library has large dependency footprint
• CSV covers 90% of use cases

Actions:

1. 🔄 Update ZenHub: Defer Excel story to backlog
2. 📝 Update Feature Brief: Document scope change in real-time

## Scope Change (2025-11-07)

**Deferred to v2**: Excel export
**Reason**: Dependency complexity too high for MVP, CSV covers 90% of needs

1. 🔄 Complete sprint with CSV only
2. ✅ Update Feature Brief with full implementation summary after sprint

---

Related Documentation

• Documentation Framework README - Complete framework guide
• Sprint Summary Template - Optional sprint tracking
• CI/CD Workflow - Deployment process

---

Troubleshooting

Issue: Feature Brief and ZenHub Stories are out of sync

Problem: Documentation says one thing, ZenHub shows different scope

Solution: This is expected! ZenHub reflects current execution reality. Update Feature Brief with "Scope Changes" section documenting divergence.

Issue: Too many updates to markdown during sprint

Problem: Constantly updating Feature Brief with daily progress

Solution: Stop updating markdown for daily progress. Only update for major scope changes or architectural decisions. Use ZenHub for daily tracking.

Issue: Don't know whether to create Feature Brief

Problem: Unsure if a task warrants formal documentation

Solution: Use decision matrix above. Generally:

• <5 points: No docs needed
• 5-13 points: Feature Brief + Technical Plan

• 13 points: Feature Brief + Technical Plan + Phases

Issue: Team members prefer ZenHub, don't check markdown

Problem: Markdown docs get stale because team lives in ZenHub

Solution: This is correct workflow! Team should use ZenHub during execution. Markdown is for:

• Planning (before sprint)
• Archival (after sprint)
• LLM collaboration (planning phase)
• Onboarding (understanding original intent)

---

Tips for Success

1. Planning phase is for markdown - Iterate quickly with LLMs and team discussion
2. Execution phase is for ZenHub - Track daily progress, blockers, and changes
3. Completion phase is for markdown - Document what shipped vs what was planned
4. Divergence is valuable - Don't try to keep them in sync during execution
5. Update markdown for majors, not minors - Major scope/architecture changes = update markdown. Daily progress = ZenHub only.
6. Delete temporary docs - Q&A files and sprint summaries should be deleted after use
7. Link everything - Epic description links to docs, docs link back to Epic

---

Last Updated: 2025-11-05