How We Manage Projects

Software is a team sport. This guide covers how we coordinate work, communicate progress, and help each other succeed.

Core principle: Communicate early, communicate often. No surprises.

GitHub as Project Hub

GitHub isn't just for code — it's our project management tool.

What Lives Where

Issues for Task Tracking

Every significant task should be a GitHub Issue.

Creating Good Issues

## Title: [Type] Brief description

### Context
Why are we doing this? Link to PRD or parent issue.

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

### Technical Notes
Any relevant implementation details.

### Related
- Blocks: #123
- Related to: #124

Issue Types

GitHub Projects Board

Organize issues visually:

┌─────────────┬─────────────┬─────────────┬─────────────┐
│   Backlog   │  Ready      │ In Progress │    Done     │
├─────────────┼─────────────┼─────────────┼─────────────┤
│ Future work │ Prioritized │ Being worked│ Completed   │
│ Not started │ Ready to go │ on now      │ this cycle  │
└─────────────┴─────────────┴─────────────┴─────────────┘

Board Rules

• One item "In Progress" per person — focus on finishing, not starting
• Move items yourself — keep the board current
• Link PRs to issues — use "Fixes #123" in PR description

Weekly Standups

We meet weekly to sync on progress and blockers.

Standup Format

Each person shares:

1. What I completed — wins since last standup
2. What I'm working on — current focus
3. Blockers — what's slowing me down

Keep it brief: 2-3 minutes per person.

Good Standup Updates

When to Raise Issues

Don't wait for standup if:

• You're completely blocked
• Something urgent broke
• You need a quick decision

Message the team immediately.

Pair Development

Two people working together on the same problem.

When to Pair

How to Pair

Driver/Navigator model:

• Driver: Types code, controls the screen
• Navigator: Reviews, thinks ahead, catches issues
• Switch every 20-30 minutes

With Claude Code:

• One person prompts and reviews
• Other person verifies and tests
• Both discuss approach before prompting

Remote Pairing

• Share screen via Discord/Google Meet
• Use VS Code Live Share for collaborative editing
• Take breaks every 45-60 minutes

Communication Patterns

Daily Communication

Async-First

We prefer async communication because:

• Respects focus time
• Creates written record
• Works across time differences

Async-friendly:

"When you have a moment, could you review PR #42?
No rush, end of day is fine."

Not async-friendly:

"Hey, you there? Quick question..."
[waits for response]
"Actually can we hop on a call?"

Asking Good Questions

When stuck, provide context:

## What I'm trying to do
Upload CSV and parse keywords

## What I expected
Keywords appear in table

## What actually happened
Error: "Cannot read property 'map' of undefined"

## What I've tried
1. Checked CSV format — looks correct
2. Console logged response — data is null
3. Verified API endpoint — returns 200

## Relevant code
[link to file or paste snippet]

Managing Blockers

Types of Blockers

Escalation Path

1. Try to solve yourself (30 min max)
2. Ask teammate
3. Ask team lead
4. Escalate to stakeholder

Don't spin on a problem for hours. Ask for help early.

Code Review

Every PR should be reviewed before merging.

As the Author

• Keep PRs small — easier to review, faster feedback
• Write good descriptions — explain what and why
• Self-review first — catch obvious issues
• Respond to feedback — don't let comments sit

As the Reviewer

• Review within 24 hours — don't block teammates
• Be constructive — suggest improvements, not just problems
• Approve or request changes — don't leave in limbo
• Focus on important issues — not just style preferences

Review Checklist

• Does the code do what the PR says?
• Are there obvious bugs or edge cases?
• Is the code understandable?
• Are there security concerns?
• Does it follow our patterns?

Handoffs and Context Sharing

When passing work to someone else:

What to Include

1. Current state — what's done, what's not
2. How to run it — environment setup, commands
3. Known issues — what doesn't work yet
4. Next steps — what to do next
5. Relevant files — where to look

Handoff Template

## Project Handoff: [Name]

### Current State
MVP is functional. User can upload keywords and see clusters.

### What's Done
- [x] Upload flow
- [x] Clustering logic
- [x] Basic results display

### What's Not Done
- [ ] Export to CSV
- [ ] Progress indicator
- [ ] Error handling for large files

### How to Run
1. Clone repo
2. Copy .env.example to .env.local
3. Add API keys (ask me for DataForSEO creds)
4. npm install && npm run dev

### Known Issues
- Clustering fails over 5000 keywords (need batching)
- No loading state during processing

### Key Files
- src/app/api/cluster/route.ts — main logic
- src/components/results-table.tsx — display component

### Questions?
Ping me on Slack.

Common Mistakes

Working in isolation

Signs: Big surprise PR after days of silence, integration problems.

Fix: Push work-in-progress, share early, ask for feedback often.

Not updating the board

Signs: Board shows wrong status, nobody knows what's in progress.

Fix: Update issue status when you start and finish work.

Sitting on blockers

Signs: "I was stuck on X for two days before asking."

Fix: 30-minute rule — if stuck for 30 minutes, ask for help.

Vague communication

Signs: "I'm working on the thing" — what thing?

Fix: Be specific. Name the issue, the file, the problem.

Evaluation Checklist

Your project management is working if:

• Everyone knows what everyone else is working on
• Blockers surface quickly
• PRs get reviewed within 24 hours
• The board reflects reality
• Standups are brief and useful
• Context is shared when handing off

Your project management needs work if:

• Surprises are common
• People work on same thing accidentally
• PRs sit unreviewed for days
• Nobody knows what's blocked
• Handoffs lose information

Quick Reference

Issue Template

## [Type] Title

### Context
Why this matters.

### Acceptance Criteria
- [ ] What done looks like

### Notes
Technical considerations.

PR Description Template

## What
Brief description of changes.

## Why
Reason for the change.

## How to Test
Steps to verify it works.

Fixes #123

Standup Template

What I finished: [completed work]
What I'm doing: [current focus]
Blockers: [anything slowing me down]