Skip to content

Project Management

Philosophy: Track work transparently, plan iteratively, ship incrementally

Overview

This directory contains templates and guidelines for project management workflows. Whether using Linear, GitHub Projects, or other tools, the principles remain the same: break work into manageable pieces, track progress, and iterate based on feedback.

Files in This Directory

linear_setup.md

Purpose: Complete Linear workspace configuration guide

Use when: Setting up Linear for team project management

Key topics: - Workspace and team structure - Issue workflow (states, types, priorities) - Cycles (sprint planning) - Roadmap planning - GitHub integration - Automation workflows

github_projects.md

Purpose: GitHub Projects configuration guide

Use when: Using GitHub native project management (free alternative to Linear)

Key topics: - Project setup (board, table, roadmap views) - Custom fields (priority, size, sprint) - Issue templates - Automation with GitHub Actions - Sprint planning workflow - Linear comparison

estimation_guidelines.md

Purpose: Team estimation standards and practices

Use when: Estimating issues, planning sprints, tracking velocity

Key topics: - Story points vs t-shirt sizing - Fibonacci scale (0, 1, 2, 3, 5, 8, 13, 21) - Planning poker process - Calibration and baselines - Velocity tracking - Audio-specific considerations

issue_templates/

Purpose: Standardized templates for common issue types

Templates: - bug_report.md - Report bugs - feature_request.md - Propose features - technical_spike.md - Research/investigation

Quick Start

Solo Developer

  1. Use GitHub Issues for task tracking
  2. Simple labels: bug, feature, priority: high
  3. Milestone per release
  4. No formal estimation (overkill for one person)

Small Team (2-5 people)

  1. Choose tool: GitHub Projects (free) or Linear ($8/user/month)
  2. Set up basic workflow: Backlog → Todo → In Progress → Review → Done
  3. Weekly triage: Review new issues, prioritize
  4. Two-week cycles (sprints)
  5. Simple estimation: Small/Medium/Large

Growing Team (5-15 people)

  1. Full Linear setup or advanced GitHub Projects
  2. Multiple project boards (per team/project)
  3. Formal estimation (story points, planning poker)
  4. Velocity tracking
  5. Sprint planning meetings
  6. Retrospectives

Workflow Comparison

Linear Workflow

1. Issue created → Lands in Backlog
2. Triage → Move to team, set priority
3. Refinement → Estimate, add to cycle
4. Sprint start → Move to Todo, assign
5. Work → Move to In Progress
6. Code review → Move to In Review (via PR)
7. PR merged → Auto-move to Done
8. Sprint end → Review, retrospective

GitHub Projects Workflow

1. Issue created → Add to project, Backlog column
2. Triage → Label, prioritize
3. Refinement → Add custom fields (size, sprint)
4. Sprint start → Move to Todo, assign
5. Work → Move to In Progress
6. Code review → PR opened, move to Review
7. PR merged → Auto-move to Done
8. Sprint end → Review, retrospective

Similarity: Almost identical, tools differ in UX and automation depth

Best Practices

Issue Writing

Good issue title: ✅ "Add SIMD optimization to FFT implementation" ✅ "Fix crash when loading presets with NaN values" ✅ "Research wavelet transform alternatives to FFT"

Bad issue title: ❌ "FFT" ❌ "Crash" ❌ "Improve performance"

Issue description must include: - Context (why is this needed?) - Scope (what's included, what's not) - Acceptance criteria (how do we know it's done?) - Links (related issues, docs, PRs)

Labels Strategy

Priority labels (when to use): - priority: urgent - Production down, user-facing critical bug - priority: high - Important deadline, major functionality - priority: medium - Normal priority (default) - priority: low - Nice to have, no rush

Type labels: - type: bug - Something is broken - type: feature - New functionality - type: improvement - Enhancement to existing feature - type: docs - Documentation work - type: testing - Test coverage

Area labels (customize for your project): - area: audio - Audio processing - area: ui - User interface - area: platform - Platform-specific - area: api - Public API - area: performance - Performance optimization

Sprint Planning

Typical two-week sprint:

Friday before (Planning): - Review previous sprint completion - Triage backlog (prioritize, estimate) - Draft scope based on velocity - Capacity: ~13 points per person - Buffer: Reserve 20% for bugs/unknowns

Monday (Sprint start): - Finalize scope - Assign issues - Brief kickoff (async or sync)

During sprint: - Daily updates (async standup) - Move issues through workflow - Flag blockers immediately

Friday (Sprint end): - Review completion rate - Demo work (optional) - Retrospective (what went well/didn't)

Estimation Tips

Use reference stories: - 1 pt = Simple parameter addition (~1 hour) - 3 pt = Basic DSP effect (~half day) - 5 pt = Complex feature with tests (~1-2 days) - 8 pt = Cross-platform feature (~2-4 days)

Break down large items: - Anything > 8 points should be broken down - Epic (21+ points) must be broken down

Estimate relative complexity: - Not absolute time - Compare to baseline stories - Use planning poker to get team alignment

See estimation_guidelines.md for details.

Velocity Tracking

Calculate velocity: 

Sprint 1: 18 points completed
Sprint 2: 22 points completed
Sprint 3: 20 points completed
───────────────────────────────
Average: 20 points/sprint

Use velocity for planning: - Team velocity: 20 points/sprint - Apply 80% buffer: Plan for 16 points - Leaves 4 points for bugs/unknowns

Velocity trends: - Stable = good (predictable) - Increasing = improving OR inflating estimates - Decreasing = harder problems OR tech debt

Issue Templates

When to Use Each Template

Bug Report - template - Something is broken - Unexpected behavior - Crash or error

Feature Request - template - New functionality - Enhancement to existing feature - User-facing change

Technical Spike - template - Investigation needed before implementation - Unclear how to approach problem - Need to evaluate alternatives - Time-boxed research

Customizing Templates

For GitHub: 1. Create .github/ISSUE_TEMPLATE/ directory 2. Add template files (markdown with YAML frontmatter) 3. Commit to repository 4. Templates appear when creating issues

For Linear: 1. Linear → Settings → Issue templates 2. Create template with markdown 3. Set as default for team or project

Integrations

Essential Integrations

GitHub ↔ Project Management: - PR opened → Issue moves to "In Review" - PR merged → Issue moves to "Done" - Branch name includes issue ID → Auto-link - Commit message includes issue ID → Auto-comment

CI/CD → Project Management: - Build failed → Comment on issue - Deployment complete → Update issue status

Chat → Project Management: - Issue created → Notify in team channel - Issue assigned → DM assignee - Issue blocked → Alert team

See ../03_12_00_communication_setup/webhooks_config.json

Metrics to Track

Sprint Metrics

  • Velocity: Points completed per sprint
  • Completion rate: % of committed work done
  • Scope creep: Work added mid-sprint
  • Blockers: How often, how long to resolve

Issue Metrics

  • Cycle time: Time from Todo → Done
  • Lead time: Time from created → Done
  • Age of backlog: How old are unstarted issues
  • Bug ratio: % of work that's bugs vs features

Team Health

  • Velocity trend: Stable, increasing, decreasing?
  • Sprint commitment accuracy: Over/under-committing?
  • Work distribution: Balanced across team?
  • Carry-over rate: Issues not finished in sprint

Review: Monthly, use to improve process

Common Anti-Patterns

❌ Too Many Priorities

Problem: Everything is urgent, nothing gets done Solution: Max 20% of backlog can be "high" priority

❌ Skipping Estimation

Problem: Can't plan capacity, surprises in sprint Solution: Estimate during refinement, not planning

❌ Scope Creep

Problem: Adding work mid-sprint breaks commitment Solution: Add to backlog, not current sprint

❌ Stale Issues

Problem: 100s of old issues cluttering backlog Solution: Archive issues older than 6 months with no activity

❌ Working Without Issue

Problem: Work happens, no tracking or documentation Solution: Create issue first, link PR to issue

❌ No Retrospectives

Problem: Same problems every sprint, no improvement Solution: 30-min retro every sprint, action items

Tools Comparison

Feature GitHub Projects Linear Jira
Cost Free $8/user/mo $7.50/user/mo
Interface Good Excellent Complex
GitHub integration Native Excellent Good
Estimation Manual Built-in Built-in
Velocity Manual Automatic Automatic
Automation Good (Actions) Excellent Extensive
Learning curve Low Low High
Best for GitHub-centric teams Modern teams Enterprise

Recommendation: - GitHub Projects: Budget-conscious, simple workflows, already on GitHub - Linear: Teams 5-50, value great UX, willing to pay - Jira: Enterprise, complex workflows, need deep customization

Templates

Sprint Planning Meeting Agenda

## Sprint #14 Planning - 2024-04-08

### Review Previous Sprint
- Velocity: 18/20 points (90% completion)
- Carry-over: 2 issues
- Blockers encountered: [list]

### This Sprint
- Team capacity: 3 people × 13 pts = 39 points
- Adjusted capacity (80%): 31 points
- Bug budget: 6 points (20%)
- Feature budget: 25 points

### Committed Work
- [ ] #123 - VST3 support (8 pts)
- [ ] #124 - Preset management (5 pts)
- [ ] #125 - Performance optimization (5 pts)
- [ ] #126 - Bug fix batch (3 pts)
- [ ] Buffer: 4 pts for unknowns

### Stretch Goals (if ahead)
- [ ] #127 - Nice-to-have feature (5 pts)

Retrospective Template

## Sprint #14 Retrospective

### What went well? ✅
-
-

### What didn't go well? ❌
-
-

### What should we try? 🎯
-
-

### Action Items
- [ ] Action 1 (Owner: @user, Due: next sprint)
- [ ] Action 2 (Owner: @user, Due: next sprint)

Next Steps

  1. Choose tool: GitHub Projects (free) vs Linear (paid)
  2. Set up workflow: Read relevant setup guide
  3. Create templates: Import issue templates
  4. Import backlog: Add existing work items
  5. Estimate: Run estimation session
  6. Plan sprint: First 2-week sprint
  7. Iterate: Retrospective, adjust process

Resources

Remember: Process serves the team, not vice versa. Start simple, iterate based on what works.