our-claude-skills/official-skills/notion-spec-to-implementation/reference/progress-tracking.md

Progress Tracking

Update Frequency

Daily Updates

For active implementation work:

What to update:

• Task status if changed
• Add progress note to task
• Update blockers

When:

• End of work day
• After completing significant work
• When encountering blockers

Milestone Updates

For phase/milestone completion:

What to update:

• Mark phase complete in plan
• Add milestone summary
• Update timeline if needed
• Report to stakeholders

When:

• Phase completion
• Major deliverable ready
• Sprint end
• Release

Status Change Updates

For task state transitions:

What to update:

• Task status property
• Add transition note
• Notify relevant people

When:

• Start work (To Do → In Progress)
• Ready for review (In Progress → In Review)
• Complete (In Review → Done)
• Block (Any → Blocked)

Progress Note Format

Daily Progress Note

## Progress: [Date]

### Completed
- [Specific accomplishment with details]
- [Specific accomplishment with details]

### In Progress
- [Current work item]
- Current status: [Percentage or description]

### Next Steps
1. [Next planned action]
2. [Next planned action]

### Blockers
- [Blocker description and who/what needed to unblock]
- Or: None

### Decisions Made
- [Any technical/product decisions]

### Notes
[Additional context, learnings, issues encountered]

Example:

## Progress: Oct 14, 2025

### Completed
- Implemented user authentication API endpoints (login, logout, refresh)
- Added JWT token generation and validation
- Wrote unit tests for auth service (95% coverage)

### In Progress
- Frontend login form integration
- Currently: Form submits but need to handle error states

### Next Steps
1. Complete error handling in login form
2. Add loading states
3. Implement "remember me" functionality

### Blockers
None

### Decisions Made
- Using HttpOnly cookies for refresh tokens (more secure than localStorage)
- Session timeout set to 24 hours based on security review

### Notes
- Found edge case with concurrent login attempts, added to backlog
- Performance of auth check is good (<10ms)

Milestone Summary

## Phase [N] Complete: [Date]

### Overview
[Brief description of what was accomplished in this phase]

### Completed Tasks
- <mention-page url="...">Task 1</mention-page> ✅
- <mention-page url="...">Task 2</mention-page> ✅
- <mention-page url="...">Task 3</mention-page> ✅

### Deliverables
- [Deliverable 1]: [Link/description]
- [Deliverable 2]: [Link/description]

### Key Accomplishments
- [Major achievement]
- [Major achievement]

### Metrics
- [Relevant metric]: [Value]
- [Relevant metric]: [Value]

### Challenges Overcome
- [Challenge and how it was solved]

### Learnings
**What went well**:
- [Success factor]

**What to improve**:
- [Area for improvement]

### Impact on Timeline
- On schedule / [X days ahead/behind]
- Reason: [If deviation, explain why]

### Next Phase
- **Starting**: [Next phase name]
- **Target start date**: [Date]
- **Focus**: [Main objectives]

Updating Implementation Plan

Progress Indicators

Update plan page regularly:

## Status Overview

**Overall Progress**: 45% complete

### Phase Status
- ✅ Phase 1: Foundation - Complete
- 🔄 Phase 2: Core Features - In Progress (60%)
- ⏳ Phase 3: Integration - Not Started

### Task Summary
- ✅ Completed: 12 tasks
- 🔄 In Progress: 5 tasks
- 🚧 Blocked: 1 task
- ⏳ Not Started: 8 tasks

**Last Updated**: [Date]

Task Checklist Updates

Mark completed tasks:

## Implementation Phases

### Phase 1: Foundation
- [x] <mention-page url="...">Database schema</mention-page>
- [x] <mention-page url="...">API scaffolding</mention-page>
- [x] <mention-page url="...">Auth setup</mention-page>

### Phase 2: Core Features
- [x] <mention-page url="...">User management</mention-page>
- [ ] <mention-page url="...">Dashboard</mention-page>
- [ ] <mention-page url="...">Reporting</mention-page>

Timeline Updates

Update milestone dates:

## Timeline

| Milestone | Original | Current | Status |
|-----------|----------|---------|--------|
| Phase 1 | Oct 15 | Oct 14 | ✅ Complete (1 day early) |
| Phase 2 | Oct 30 | Nov 2 | 🔄 In Progress (3 days delay) |
| Phase 3 | Nov 15 | Nov 18 | ⏳ Planned (adjusted) |
| Launch | Nov 20 | Nov 22 | ⏳ Planned (adjusted) |

**Timeline Status**: Slightly behind due to [reason]

Task Status Tracking

Status Definitions

To Do: Not started

• Task is ready to begin
• Dependencies met
• Assigned (or available)

In Progress: Actively being worked

• Work has started
• Assigned to someone
• Regular updates expected

Blocked: Cannot proceed

• Dependency not met
• External blocker
• Waiting on decision/resource

In Review: Awaiting review

• Work complete from implementer perspective
• Needs code review, QA, or approval
• Reviewers identified

Done: Complete

• All acceptance criteria met
• Reviewed and approved
• Deployed/delivered

Updating Task Status

When updating:

1. Update Status property
2. Add progress note explaining change
3. Update related tasks if needed
4. Notify relevant people via comment

Example:
properties: { "Status": "In Progress" }

Content update:
## Progress: Oct 14, 2025
Started implementation. Set up basic structure and wrote initial tests.

Blocker Tracking

Recording Blockers

When encountering a blocker:

## Blockers

### [Date]: [Blocker Description]
**Status**: 🚧 Active
**Impact**: [What's blocked]
**Needed to unblock**: [Action/person/decision needed]
**Owner**: [Who's responsible for unblocking]
**Target resolution**: [Date or timeframe]

Resolving Blockers

When unblocked:

## Blockers

### [Date]: [Blocker Description]
**Status**: ✅ Resolved on [Date]
**Resolution**: [How it was resolved]
**Impact**: [Any timeline/scope impact]

Escalating Blockers

If blocker needs escalation:

1. Update blocker status in task
2. Add comment tagging stakeholder
3. Update plan with blocker impact
4. Propose mitigation if possible

Metrics Tracking

Velocity Tracking

Track completion rate:

## Velocity

### Week 1
- Tasks completed: 8
- Story points: 21
- Velocity: Strong

### Week 2
- Tasks completed: 6
- Story points: 18
- Velocity: Moderate (1 blocker)

### Week 3
- Tasks completed: 9
- Story points: 24
- Velocity: Strong (blocker resolved)

Quality Metrics

Track quality indicators:

## Quality Metrics

- Test coverage: 87%
- Code review approval rate: 95%
- Bug count: 3 (2 minor, 1 cosmetic)
- Performance: All targets met
- Security: No issues found

Progress Metrics

Quantitative progress:

## Progress Metrics

- Requirements implemented: 15/20 (75%)
- Acceptance criteria met: 42/56 (75%)
- Test cases passing: 128/135 (95%)
- Code complete: 80%
- Documentation: 60%

Stakeholder Communication

Weekly Status Report

## Weekly Status: [Week of Date]

### Summary
[One paragraph overview of progress and status]

### This Week's Accomplishments
- [Key accomplishment]
- [Key accomplishment]
- [Key accomplishment]

### Next Week's Plan
- [Planned work]
- [Planned work]

### Status
- On track / At risk / Behind schedule
- [If at risk or behind, explain and provide mitigation plan]

### Blockers & Needs
- [Active blocker or need for help]
- Or: None

### Risks
- [New or evolving risk]
- Or: None currently identified

Executive Summary

For leadership updates:

## Implementation Status: [Feature Name]

**Overall Status**: 🟢 On Track / 🟡 At Risk / 🔴 Behind

**Progress**: [X]% complete

**Key Updates**:
- [Most important update]
- [Most important update]

**Timeline**: [Status vs original plan]

**Risks**: [Top 1-2 risks]

**Next Milestone**: [Upcoming milestone and date]

Automated Progress Tracking

Query-Based Status

Generate status from task database:

Query task database:
SELECT 
  "Status",
  COUNT(*) as count
FROM "collection://tasks-uuid"
WHERE "Related Tasks" CONTAINS 'plan-page-id'
GROUP BY "Status"

Generate summary:
- To Do: 8
- In Progress: 5
- Blocked: 1
- In Review: 2
- Done: 12

Overall: 44% complete (12/28 tasks)

Timeline Calculation

Calculate projected completion:

Average velocity: 6 tasks/week
Remaining tasks: 14
Projected completion: 2.3 weeks from now

Compares to target: [On schedule/Behind/Ahead]

Best Practices

1. Update regularly: Don't let updates pile up
2. Be specific: "Completed login" vs "Made progress"
3. Quantify progress: Use percentages, counts, metrics
4. Note blockers immediately: Don't wait to report blockers
5. Link to work: Reference PRs, deployments, demos
6. Track decisions: Document why, not just what
7. Be honest: Report actual status, not optimistic status
8. Update in one place: Keep implementation plan as source of truth