Project Roadmap Management

Overview

Manage project roadmaps using a minimalist, position-based priority system. Core philosophy: Position = Priority. Items at the top have the highest value.

This skill helps create and maintain ROADMAP.md files using a simple, effective structure that eliminates complex priority matrices and scoring systems.

Core Philosophy

Position = Priority: Instead of calculating ICE scores or filling priority matrices, manually arrange items by importance. What's at the top matters most.

Simplicity over Process: No complex tracking systems. If a task sits in Backlog for 3+ months untouched, delete it or move to Someday.

Focus on Execution: Limit "Doing" to 2-3 items max. Context switching kills productivity.

ROADMAP Structure

📥 Inbox          → Quick capture, weekly cleanup
🏗️ Execution
  🟢 Doing        → Active work (Max 2-3 items)
  🟡 Next Up      → Ordered by value/urgency
  ⚪ Backlog      → Future tasks, not urgent
📔 Done           → Recent completions (keep last 5)
📜 CHANGELOG.md   → Full completion history

Section Guidelines

Inbox

• Temporary holding area for quick thoughts
• Review weekly: promote to Execution or delete
• Examples: "Consider payment integration", "Fix typo on profile page"

Doing (Max 2-3)

• Currently active code/work
• Strict limit prevents context switching
• Include current status in parentheses

Next Up

• Ordered list: top = highest priority
• Manual sorting replaces priority scoring
• Critical bugs (🔴 P0) go first
• High-demand features come before nice-to-haves

Backlog

• Future tasks, no urgency
• Review monthly: promote or delete stale items
• If untouched for 3+ months, probably deletable

Done

• Keep only the last 5 completed items for recent visibility
• Include link to CHANGELOG.md for full history
• Format: - [x] Description - YYYY-MM-DD
• Older completions should be archived to CHANGELOG.md

Common Operations

Initialize a New Roadmap

Copy templates to the project root:

cp assets/ROADMAP.md /path/to/project/ROADMAP.md
cp assets/CHANGELOG.md /path/to/project/CHANGELOG.md

Add a New Task

1. Quick capture → Add to Inbox
2. Planned task → Add directly to appropriate section:
   • Critical bug → Top of "Next Up" or insert into "Doing"
   • Normal feature → "Next Up" ordered by priority
   • Future idea → "Backlog"

Prioritize Tasks

Manual reordering in "Next Up":

1. Cut the task line
2. Paste it in the new position
3. Top = highest priority, bottom = lowest

No calculation needed. Trust your judgment on what matters most.

Move Task Status

Starting work: Cut from "Next Up" → Paste into "Doing"
Completing work: Change [ ] to [x], cut → paste into "Done"
Deprioritizing: Cut → paste into "Backlog"

Handle Bugs

• Critical (🔴 P0): Top of "Next Up" or insert into "Doing" immediately
• Minor (🟡): Add to "Backlog", fix when changing mental context

Archive Completed Tasks to CHANGELOG

When the "Done" section has more than 5 items, archive older ones to CHANGELOG.md:

1. Extract tasks to archive: Take items beyond the 5 most recent from "Done" section
2. Get commit info (if applicable): Run git log --all --fixed-strings --grep="<task-description>" to find related commits
3. Add to CHANGELOG.md:
   • Group by date (format: ## [YYYY-MM-DD])
   • Format: - [x] Description - YYYY-MM-DD ([commit-hash](commit-url))
   • Place newer dates at the top
4. Clean ROADMAP.md: Remove archived items, keep only last 5 in "Done"

Example CHANGELOG.md entry:

## [2024-01-15]

- [x] #021 重构 LLM 接口层 - 2024-01-15 ([abc123f](https://github.com/user/repo/commit/abc123f))
- [x] 集成 Gemini API - 2024-01-15

Weekly Cleanup

1. Review Inbox: promote or delete each item
2. Check Backlog: delete anything 3+ months old and untouched
3. Ensure "Doing" has max 2-3 items
4. Reorder "Next Up" based on current priorities
5. Archive "Done" items to CHANGELOG.md if more than 5

Workflow Integration

VS Code Setup

1. Pin the file: Right-click ROADMAP.md → Pin tab
2. Quick capture: Write // TODO: xxx in code, transfer to Inbox later
3. Pre-commit review: Check ROADMAP before git commit, update status

Commit Hook Pattern

Before committing:

1. Review what was completed
2. Update [ ] → [x] for finished tasks
3. Move completed items to "Done" section
4. Add any new tasks discovered during work to Inbox

Task Format Examples

## 📥 Inbox
- [ ] Consider adding payment gateway integration
- [ ] Fix typo in user profile header

## 🟢 Doing (Max 2-3)
- [ ] #021 Refactor LLM interface layer (handling streaming output)

## 🟡 Next Up
- [ ] [BUG] Fix API timeout on high concurrency (🔴 P0)
- [ ] #018 Mobile layout adaptation (highest user demand)
- [ ] #022 Integrate Gemini API
- [ ] Add caching layer for frequently accessed data

## ⚪ Backlog
- [ ] PDF export functionality
- [ ] Multi-language i18n support

## 📔 Done
> 最近完成（查看完整历史 → [CHANGELOG.md](CHANGELOG.md)）
- [x] #021 重构 LLM 接口层 - 2024-01-15
- [x] 集成 Gemini API - 2024-01-14
- [x] 修复 API 超时问题 - 2024-01-13
- [x] 添加缓存层 - 2024-01-10
- [x] 移动端适配 - 2024-01-09

Best Practices

1. Keep Doing small: 2-3 items max. Finish before starting new work.
2. Trust manual ordering: Don't second-guess priority placement. Top = most important.
3. Weekly Inbox zero: Clear Inbox every week. Decide or delete.
4. Delete aggressively: Backlog items untouched for 3+ months rarely matter.
5. Context in parentheses: Add current status to "Doing" items.
6. Bug triage: P0 bugs jump the queue. P1-P2 go to Backlog.

Resources

This skill includes:

assets/ROADMAP.md - Template file ready to copy to any project root
assets/CHANGELOG.md - Template file for tracking completion history