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

markdown

# {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

| Risk             | Impact          | Mitigation          |
| ---------------- | --------------- | ------------------- |
| Risk description | High/Medium/Low | Mitigation strategy |

## Open Questions

- [ ] Question that needs resolution
- [x] Resolved question - Answer

Plan (plan.md) Structure

markdown

# 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

| Phase   | Checkpoint SHA | Date | Status  |
| ------- | -------------- | ---- | ------- |
| Phase 1 |                |      | pending |
| Phase 2 |                |      | pending |
| Phase 3 |                |      | pending |

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:

markdown

- [x] **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

markdown

# Track Registry

## Active Tracks

| Track ID                                                         | Type    | Status      | Phase | Started    | Assignee   |
| ---------------------------------------------------------------- | ------- | ----------- | ----- | ---------- | ---------- |
| [user-auth_20250115](.claude/context/tracks/user-auth_20250115/) | feature | in-progress | 2/3   | 2025-01-15 | @developer |
| [fix-login_20250114](.claude/context/tracks/fix-login_20250114/) | bug     | pending     | 0/2   | 2025-01-14 | -          |

## Completed Tracks

| Track ID                                                       | Type  | Completed  | Duration |
| -------------------------------------------------------------- | ----- | ---------- | -------- |
| [setup-ci_20250110](.claude/context/tracks/setup-ci_20250110/) | chore | 2025-01-12 | 2 days   |

## Archived Tracks

| Track ID                                                             | Reason     | Archived   |
| -------------------------------------------------------------------- | ---------- | ---------- |
| [old-feature_20241201](.claude/context/tracks/old-feature_20241201/) | Superseded | 2025-01-05 |

Metadata (metadata.json) Fields

json

{
  "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

Memory Protocol (MANDATORY)

Before starting:

bash

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.

track-management

NPX Install

Tags

SKILL.md Content

Track Management

When to Use This Skill

Track Concept

Track Types

feature

bug

chore

refactor

Track ID Format

Track Lifecycle

1. Creation (newTrack)

2. Implementation

3. Completion

Specification (spec.md) Structure

Plan (plan.md) Structure

Status Marker Conventions

Track Registry (tracks.md) Format

Metadata (metadata.json) Fields

Track Sizing Guidelines

Right-Sized Tracks

Too Large

Too Small

Common Track Patterns

Feature Track Pattern

Bug Fix Track Pattern

Refactor Track Pattern

Best Practices

Memory Protocol (MANDATORY)