Managing Tracks

Part III: Track Lifecycle · Chapter 11

4 min read

Specs get written. Plans get approved. Implementation begins. And then the requirements change. Or a task gets blocked by an external dependency. Or you realize phase 2 introduced a regression and need to undo it without losing phase 1's work. Draft provides three operational commands for exactly these situations: /draft:status for visibility, /draft:change for mid-track adjustments, and /draft:revert for git-aware rollback.

Status: Project Visibility

/draft:status reads every active track's plan and metadata, then produces a comprehensive dashboard showing exactly where everything stands.

$ /draft:status

═══════════════════════════════════════════════════════════
                      DRAFT STATUS
═══════════════════════════════════════════════════════════

PROJECT: Acme Platform

ACTIVE TRACKS
─────────────────────────────────────────────────────────
[add-oauth2] Add OAuth2 Support
  Status: [~] In Progress
  Phase:  2/3 (Phase 2: Provider Integration)
  Tasks:  6/11 complete
  ├─ [x] Task 1.1: Create OAuth provider config (a1b2c3d)
  ├─ [x] Task 1.2: Add linked_accounts migration (b2c3d4e)
  ├─ [x] Task 1.3: Implement token exchange (c3d4e5f)
  ├─ [x] Task 1.4: Write token exchange tests (d4e5f6a)
  ├─ [x] Task 2.1: Google OAuth callback (e5f6a7b)
  ├─ [x] Task 2.2: GitHub OAuth callback (f6a7b8c)
  ├─ [~] Task 2.3: Rate limiting on callbacks  ← CURRENT
  ├─ [ ] Task 2.4: Integration tests
  ├─ [ ] Task 3.1: Linked accounts UI
  ├─ [ ] Task 3.2: Token revocation
  └─ [ ] Task 3.3: End-to-end tests

[fix-email-null] Fix Null Pointer in Email Validation
  Status: [~] In Progress
  Type:   quick
  Tasks:  1/3 complete
  ├─ [x] Task 1: Add null check (g7h8i9j)
  ├─ [~] Task 2: Write regression test  ← CURRENT
  └─ [ ] Task 3: Verify fix in staging

BLOCKED ITEMS
─────────────────────────────────────────────────────────
  (none)

QUICK STATS
─────────────────────────────────────────────────────────
Active Tracks:    2
Total Tasks:      14
Completed:        7 (50%)
Blocked:          0
═══════════════════════════════════════════════════════════

The status display adapts to track type. Multi-phase tracks show phase progress with nested task trees. Quick-mode tracks show a flat task list without phase grouping. Both use the same status markers: [ ] Pending, [~] In Progress, [x] Completed, [!] Blocked.

Orphaned Track Detection

The status command also scans for orphaned tracks — directories in draft/tracks/ that have a metadata.json but no corresponding entry in tracks.md. These can occur when a track creation was interrupted between directory creation and registry update. The status output flags them with recovery options: add the entry to tracks.md manually, or remove the orphaned directory.

Module Reporting

When .ai-context.md or architecture.md exists, the status output includes a module-level view — which modules are complete, which are in progress with task counts, and which are blocked. This gives architectural visibility alongside task-level progress.

Change: Mid-Track Adjustments

Requirements change. A stakeholder wants JSON export added to a feature that was specced for CSV only. A security review reveals a new constraint. A dependency you planned to use is deprecated. /draft:change handles these mid-stream adjustments without losing completed work.

$ /draft:change the export format should support JSON in addition to CSV

The command follows a structured process:

1. Impact Analysis — The AI classifies every requirement and acceptance criterion in spec.md as Added, Modified, Removed, or Unaffected by the change.
2. Plan Mapping — Each task in plan.md is evaluated against the spec change. Completed tasks that are now invalidated get flagged for potential rework. In-progress tasks get flagged for review. Pending tasks get proposed new text.
3. Preview — The full impact is displayed before any file is modified: how many completed tasks may need rework, how many pending tasks need updating, the exact before/after diffs for each affected section.
4. Confirmation — You approve, reject, or request edits to the proposed changes. The edit loop continues until you say "yes" or "no."
5. Application — On approval, amendments are applied to spec.md and plan.md, metadata timestamps are updated, and a Change Log entry is appended to the plan with the current git SHA and timestamp.

Change: Add JSON export format
Track:  add-export-feature

Spec impact:
  - Modified: AC #2 "User can export to CSV" → now also requires JSON
  - Removed:  AC #5 "Export limited to 1000 rows"
  - Added:    AC #6 "Export progress indicator for large datasets"

Plan impact:
  - 1 completed task may need rework
  - 2 pending tasks need updating
  - 0 blocked tasks affected

Completed tasks that may need rework:
  - [x] Task 1.3: Implement CSV serializer (abc1234)

Apply these changes to spec.md and plan.md? [yes / no / edit]

Revert: Git-Aware Rollback

Sometimes you need to undo work. A phase introduced a subtle regression. An approach turned out to be a dead end. A task's implementation conflicts with a concurrent change on another branch. /draft:revert provides git-aware rollback that understands Draft's logical units of work.

The command supports three granularity levels:

• Task-level revert — Undo a single task's commits. The most surgical option.
• Phase-level revert — Undo all commits in an entire phase. Useful when the approach for a phase was wrong.
• Track-level revert — Undo everything in the track. The nuclear option.

Every revert follows the same safety protocol:

1. Pre-flight check — Verifies the working tree is clean. Uncommitted changes must be stashed or committed first.
2. Commit identification — Reads commit SHAs from the [x] task markers in plan.md. Falls back to searching git log by track ID pattern if SHAs are missing.
3. Preview — Shows exactly which commits will be reverted, which files are affected, and how plan.md will change. Nothing happens without your confirmation.
4. Execution — Reverts commits in reverse chronological order using git revert --no-commit, then creates a single revert commit: revert(add-oauth2): Revert Phase 2 provider integration.
5. State update — Reverted tasks change from [x] to [ ] in plan.md. The commit SHA is removed. metadata.json counters are decremented. Phase status markers are adjusted — if any task in a completed phase is reverted, the phase returns to In Progress.

$ /draft:revert

Reverting: Phase 2 "Provider Integration"

Commits to revert (newest first):
  f6a7b8c feat(add-oauth2): GitHub OAuth callback
  e5f6a7b feat(add-oauth2): Google OAuth callback

Files affected:
  src/auth/google.ts
  src/auth/github.ts
  tests/auth/google.test.ts
  tests/auth/github.test.ts

Plan.md changes:
  Task 2.1: [x] (e5f6a7b) → [ ]
  Task 2.2: [x] (f6a7b8c) → [ ]

Proceed with revert? (yes/no)

Handling Blocked Tasks

When a task cannot proceed, it is marked [!] Blocked with a reason recorded in plan.md. The implementation command skips blocked tasks and notifies you, but it never attempts to implement them. Blocked tasks require manual intervention — resolving an external dependency, getting an API key provisioned, waiting for a team member's input.

/draft:status surfaces all blocked items in a dedicated section, making them visible even if you're focused on a different part of the project. When the blocker is resolved, you manually change the marker from [!] to [ ] and resume implementation.

Track Completion

When all tasks in all phases are marked [x], the implementation command runs a final review (if auto-review is enabled in workflow.md), updates plan.md status to Completed, sets metadata.json status to "completed", and moves the track from the Active section to the Completed section in tracks.md with a completion date. The AI verifies all three files are consistent before announcing completion — if any file shows inconsistent state, it halts and reports exactly what needs manual correction.

Track add-oauth2 completed!

Summary:
- Phases: 3/3
- Tasks: 11/11

Review: PASS
Report: draft/tracks/add-oauth2/review-report-latest.md

All acceptance criteria from spec.md verified.
Next: Run /draft:status to see project overview.

The completed track remains in the project history. Its specification, plan, and review reports are preserved as a permanent record of what was built, why it was built, and how it was verified. This trail becomes valuable context for future tracks that touch the same areas of the codebase.