121 lines
3.4 KiB
Markdown
121 lines
3.4 KiB
Markdown
# Progress Tracking
|
|
|
|
## Plan Analysis Workflow
|
|
|
|
1. **Read plans directory:** Glob `./plans/*/plan.md` to discover all plans
|
|
2. **Parse YAML frontmatter:** Extract status, priority, effort, branch, tags
|
|
3. **Scan phase files:** Count `[x]` (done) vs `[ ]` (remaining) in each phase
|
|
4. **Reconcile completed tasks:** Ensure all completed task metadata is reflected in phase files (backfill stale earlier phases first)
|
|
5. **Calculate progress:** `completed / total * 100` per plan
|
|
6. **Cross-reference:** Compare plan tasks against actual implementation
|
|
|
|
## Status Update Protocol
|
|
|
|
### CLI-First Status Updates (Preferred)
|
|
|
|
Use `ck plan` CLI commands for deterministic, format-safe status changes:
|
|
|
|
```bash
|
|
# Mark phase completed
|
|
ck plan check <phase-id>
|
|
|
|
# Mark phase in-progress
|
|
ck plan check <phase-id> --start
|
|
|
|
# Revert phase to pending
|
|
ck plan uncheck <phase-id>
|
|
|
|
# Add new phase or sub-phase
|
|
ck plan add-phase "Phase Name" [--after <id>]
|
|
```
|
|
|
|
CLI automatically updates both `plan.md` table AND phase file frontmatter.
|
|
Plan-level status auto-computed: all completed → `completed`, any in-progress → `in-progress`.
|
|
|
|
**Fallback:** If `ck` CLI is not available, edit `plan.md` directly —
|
|
only change the Status column cell, preserve table structure exactly.
|
|
|
|
### Plan-Level Status
|
|
|
|
Update `plan.md` frontmatter `status` field:
|
|
|
|
| Condition | Status |
|
|
|-----------|--------|
|
|
| No phases started | `pending` |
|
|
| Any phase in progress | `in-progress` |
|
|
| All phases complete | `completed` |
|
|
|
|
### Phase-Level Status
|
|
|
|
Each `phase-XX-*.md` tracks with checkboxes:
|
|
- `[ ]` = pending
|
|
- `[x]` = completed
|
|
- Count ratio for progress percentage
|
|
|
|
### Task-Level Status
|
|
|
|
Claude Tasks (session-scoped): `pending` → `in_progress` → `completed`
|
|
|
|
### Reconciliation Rule
|
|
|
|
If a later phase is marked done while earlier phases still contain stale unchecked completed items, backfill earlier phases in the same sync pass before final status reporting.
|
|
|
|
## Verification Checklist
|
|
|
|
When verifying task completeness:
|
|
|
|
1. **Acceptance criteria met?** — Check against plan requirements
|
|
2. **Code quality validated?** — code-reviewer agent report available?
|
|
3. **Tests passing?** — tester agent report confirms 100% pass?
|
|
4. **Documentation updated?** — docs match implementation?
|
|
5. **No regressions?** — Existing functionality intact?
|
|
|
|
## Report Generation
|
|
|
|
### Status Summary Template
|
|
|
|
```markdown
|
|
## Project Status: [Date]
|
|
|
|
### Active Plans
|
|
| Plan | Progress | Priority | Status | Branch |
|
|
|------|----------|----------|--------|--------|
|
|
| [name] | [X]% | P[N] | [status] | [branch] |
|
|
|
|
### Completed This Session
|
|
- [x] [description]
|
|
|
|
### Blockers & Risks
|
|
- [ ] [description] — [mitigation]
|
|
|
|
### Next Steps
|
|
1. [Priority action]
|
|
2. [Follow-up]
|
|
```
|
|
|
|
### Detailed Report Template
|
|
|
|
```markdown
|
|
## [Plan Name] - Detailed Status
|
|
|
|
### Achievements
|
|
- Completed features, resolved issues, delivered value
|
|
|
|
### Testing Status
|
|
- Components needing validation, test scenarios, quality gates
|
|
|
|
### Risk Assessment
|
|
- Potential blockers, technical debt, mitigation strategies
|
|
|
|
### Recommendations
|
|
- Prioritized next steps, resource needs, timeline projections
|
|
```
|
|
|
|
## Metrics to Track
|
|
|
|
- **Phase completion %** — How much of each phase is done
|
|
- **Blocker count** — Open blockers preventing progress
|
|
- **Dependency chain health** — Any circular or stale dependencies
|
|
- **Time since last update** — Identify stale plans needing attention
|
|
- **Test coverage** — Per-feature test pass rates
|