Track Management

Guide for creating, managing, and completing tracks - the logical work units that organize features, bugs, and refactors through specification, planning, and implementation phases.

When to Use This Skill

• Creating new feature, bug, or refactor tracks

• Writing or reviewing spec.md files

• Creating or updating plan.md files

• Managing track lifecycle from creation to completion

• Understanding track status markers and conventions

• Working with the tracks.md registry

• Interpreting or updating track metadata

Track Concept

A track is a logical work unit that encapsulates a complete piece of work. Each track has:

• A unique identifier

• A specification defining requirements

• A phased plan breaking work into tasks

• Metadata tracking status and progress

Tracks provide semantic organization for work, enabling:

• Clear scope boundaries

• Progress tracking

• Git-aware operations (revert by track)

• Team coordination

Track Types

feature

New functionality or capabilities. Use for:

• New user-facing features

• New API endpoints

• New integrations

• Significant enhancements

bug

Defect fixes. Use for:

• Incorrect behavior

• Error conditions

• Performance regressions

• Security vulnerabilities

chore

Maintenance and housekeeping. Use for:

• Dependency updates

• Configuration changes

• Documentation updates

• Cleanup tasks

refactor

Code improvement without behavior change. Use for:

• Code restructuring

• Pattern adoption

• Technical debt reduction

• Performance optimization (same behavior, better performance)

Track ID Format

Track IDs follow the pattern: {shortname}_{YYYYMMDD}

• shortname: 2-4 word kebab-case description (e.g., user-auth , api-rate-limit )

• YYYYMMDD: Creation date in ISO format

Examples:

• user-auth_20250115

• fix-login-error_20250115

• upgrade-deps_20250115

• refactor-api-client_20250115

Track Lifecycle

1. Creation (newTrack)

Define Requirements

• Gather requirements through interactive Q&A

• Identify acceptance criteria

• Determine scope boundaries

• Identify dependencies

Generate Specification

• Create spec.md with structured requirements

• Document functional and non-functional requirements

• Define acceptance criteria

• List dependencies and constraints

Generate Plan

• Create plan.md with phased task breakdown

• Organize tasks into logical phases

• Add verification tasks after phases

• Estimate effort and complexity

Register Track

• Add entry to tracks.md registry

• Create track directory structure

• Generate metadata.json

• Create track index.md

2. Implementation

Execute Tasks

• Select next pending task from plan

• Mark task as in-progress

• Implement following workflow (TDD)

• Mark task complete with commit SHA

Update Status

• Update task markers in plan.md

• Record commit SHAs for traceability

• Update phase progress

• Update track status in tracks.md

Verify Progress

• Complete verification tasks

• Wait for checkpoint approval

• Record checkpoint commits

3. Completion

Sync Documentation

• Update product.md if features added

• Update tech-stack.md if dependencies changed

• Verify all acceptance criteria met

Archive or Delete

• Mark track as completed in tracks.md

• Record completion date

• Archive or retain track directory

Specification (spec.md) Structure

{Track Title}

Overview

Brief description of what this track accomplishes and why.

Functional Requirements

FR-1: {Requirement Name}

Description of the functional requirement.

• Acceptance: How to verify this requirement is met

FR-2: {Requirement Name}

...

Non-Functional Requirements

NFR-1: {Requirement Name}

Description of the non-functional requirement (performance, security, etc.)

• Target: Specific measurable target
• Verification: How to test

Acceptance Criteria

• Criterion 1: Specific, testable condition
• Criterion 2: Specific, testable condition
• Criterion 3: Specific, testable condition

Scope

In Scope

• Explicitly included items
• Features to implement
• Components to modify

Out of Scope

• Explicitly excluded items
• Future considerations
• Related but separate work

Dependencies

Internal

• Other tracks or components this depends on
• Required context artifacts

External

• Third-party services or APIs
• External dependencies

Risks and Mitigations

Open Questions

• Question that needs resolution
• Resolved question - Answer

Plan (plan.md) Structure

Implementation Plan: {Track Title}

Track ID: {track-id} Created: YYYY-MM-DD Status: pending | in-progress | completed

Overview

Brief description of implementation approach.

Phase 1: {Phase Name}

Tasks

• Task 1.1: Task description
  • Sub-task or detail
  • Sub-task or detail
• Task 1.2: Task description
• Task 1.3: Task description

Verification

• Verify 1.1: Verification step for phase

Phase 2: {Phase Name}

Tasks

• Task 2.1: Task description
• Task 2.2: Task description

Verification

• Verify 2.1: Verification step for phase

Phase 3: Finalization

Tasks

• Task 3.1: Update documentation
• Task 3.2: Final integration test

Verification

• Verify 3.1: All acceptance criteria met

Checkpoints

Status Marker Conventions

Use consistent markers in plan.md:

Marker Meaning Usage

[ ]

Pending Task not started

[~]

In Progress Currently being worked

[x]

Complete Task finished (include SHA)

[-]

Skipped Intentionally not done

[!]

Blocked Waiting on dependency

Example:

• Task 1.1: Set up database schema abc1234
• [~] Task 1.2: Implement user model
• Task 1.3: Add validation logic
• [!] Task 1.4: Integrate auth service (blocked: waiting for API key)
• [-] Task 1.5: Legacy migration (skipped: not needed)

Track Registry (tracks.md) Format

Track Registry

Active Tracks

Completed Tracks

Archived Tracks

Metadata (metadata.json) Fields

{ "id": "user-auth_20250115", "title": "User Authentication System", "type": "feature", "status": "in-progress", "priority": "high", "created": "2025-01-15T10:30:00Z", "updated": "2025-01-15T14:45:00Z", "started": "2025-01-15T11:00:00Z", "completed": null, "assignee": "@developer", "phases": { "total": 3, "current": 2, "completed": 1 }, "tasks": { "total": 12, "completed": 5, "in_progress": 1, "pending": 6 }, "checkpoints": [ { "phase": 1, "sha": "abc1234", "date": "2025-01-15T13:00:00Z" } ], "dependencies": [], "tags": ["auth", "security"] }

Track Sizing Guidelines

Right-Sized Tracks

Aim for tracks that:

• Complete in 1-5 days of work

• Have 2-4 phases

• Contain 8-20 tasks total

• Deliver a coherent, testable unit

Too Large

Signs a track is too large:

• More than 5 phases

• More than 25 tasks

• Multiple unrelated features

• Estimated duration > 1 week

Solution: Split into multiple tracks with clear boundaries.

Too Small

Signs a track is too small:

• Single phase with 1-2 tasks

• No meaningful verification needed

• Could be a sub-task of another track

• Less than a few hours of work

Solution: Combine with related work or handle as part of existing track.

Common Track Patterns

Feature Track Pattern

Phase 1: Foundation

• Data models
• Database migrations
• Basic API structure

Phase 2: Core Logic

• Business logic implementation
• Input validation
• Error handling

Phase 3: Integration

• UI integration
• API documentation
• End-to-end tests

Bug Fix Track Pattern

Phase 1: Reproduction

• Write failing test capturing bug
• Document reproduction steps

Phase 2: Fix

• Implement fix
• Verify test passes
• Check for regressions

Phase 3: Verification

• Manual verification
• Update documentation if needed

Refactor Track Pattern

Phase 1: Preparation

• Add characterization tests
• Document current behavior

Phase 2: Refactoring

• Apply changes incrementally
• Maintain green tests throughout

Phase 3: Cleanup

• Remove dead code
• Update documentation

Best Practices

• One track, one concern: Keep tracks focused on a single logical change

• Small phases: Break work into phases of 3-5 tasks maximum

• Verification after phases: Always include verification tasks

• Update markers immediately: Mark task status as you work

• Record SHAs: Always note commit SHAs for completed tasks

• Review specs before planning: Ensure spec is complete before creating plan

• Link dependencies: Explicitly note track dependencies

• Archive, don't delete: Preserve completed tracks for reference

• Size appropriately: Keep tracks between 1-5 days of work

• Clear acceptance criteria: Every requirement must be testable

Iron Laws

• ALWAYS create the track directory and spec.md before writing any implementation code

• NEVER begin implementation without a committed plan.md with task breakdown and dependencies

• ALWAYS record session progress in progress.md at the end of every working session

• NEVER mark a task [x] complete without a commit SHA proving the work was committed

• ALWAYS move blocked tasks to [!] with a description of the blocker rather than leaving them in-progress

Anti-Patterns

Anti-Pattern Why It Fails Correct Approach

Implementation without spec.md Undefined requirements and scope creep Write spec.md first; block implementation until done

plan.md not updated as tasks complete Stale plan misleads next session Update task states in real time as work progresses

No progress.md entries between sessions Lost context on resume, duplicate work Append session log to progress.md before stopping

Marking [x] without commit SHA No traceability; can't verify what was done Record commit SHA with every completed task

Ignoring blocked tasks Silent blockers derail the track Escalate [!] blockers immediately; don't skip

Memory Protocol (MANDATORY)

Before starting:

cat .claude/context/memory/learnings.md

After completing:

• New pattern -> .claude/context/memory/learnings.md

• Issue found -> .claude/context/memory/issues.md

• Decision made -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.