---
name: track-management
description: Use this skill when creating, managing, or working with Conductor tracks - the logical work units for features, bugs, and refactors. Applies to spec.md, plan.md, and track lifecycle operations.
version: 1.0.0
enabled: false
source: github:JuanJoseGonGi/skills
imported-from: github:JuanJoseGonGi/skills
---

# Track Management

Guide for creating, managing, and completing Conductor 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
- Working with the tracks.md registry

## Reference Files

Load these for detailed templates, examples, and guidelines:

| Reference | Contents |
|-----------|----------|
| `references/spec-template.md` | Full spec.md template and quality checklist |
| `references/plan-template.md` | Full plan.md template and quality checklist |
| `references/registry-and-metadata.md` | tracks.md format and metadata.json schema |
| `references/track-patterns.md` | Feature/bug/refactor phase patterns and sizing guidelines |
| `references/dependencies-guide.md` | Dependency types, documentation, and blocked track handling |

## Track Concept

A track is a logical work unit with: a unique ID, a specification (requirements), a phased plan (tasks), and metadata (status/progress). Tracks provide clear scope boundaries, progress tracking, git-aware operations (revert by track), and team coordination.

## Track Types

| Type | Purpose | Examples |
|------|---------|----------|
| **feature** | New functionality | New features, API endpoints, integrations |
| **bug** | Defect fixes | Incorrect behavior, errors, regressions, security |
| **chore** | Maintenance | Dependency updates, config, docs, cleanup |
| **refactor** | Code improvement (no behavior change) | Restructuring, pattern adoption, tech debt |

## Track ID Format

Pattern: `{shortname}_{YYYYMMDD}`

- **shortname**: 2-4 word kebab-case description
- **YYYYMMDD**: Creation date

Examples: `user-auth_20250115`, `fix-login-error_20250115`, `refactor-api-client_20250115`

## Track Lifecycle

### 1. Creation

1. Gather requirements through interactive Q&A
2. Create `spec.md` with structured requirements and acceptance criteria → see `references/spec-template.md`
3. Create `plan.md` with phased task breakdown → see `references/plan-template.md`
4. Register in `tracks.md` and generate `metadata.json` → see `references/registry-and-metadata.md`

### 2. Implementation

1. Select next pending task from plan, mark as `[~]`
2. Implement following TDD workflow
3. Mark task complete `[x]` with commit SHA
4. After all phase tasks complete, run verification tasks
5. Wait for checkpoint approval, record checkpoint SHA
6. Proceed to next phase

### 3. Completion

1. Verify all phases and acceptance criteria complete
2. Update product.md / tech-stack.md if needed
3. Mark track completed in tracks.md, record completion date

## Status Markers

Use in plan.md task lists:

| 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 Operations

### Creating a Track

1. Run `/conductor:new-track`
2. Answer interactive questions
3. Review generated spec.md
4. Review generated plan.md
5. Confirm track creation

### Starting Implementation

1. Read spec.md and plan.md
2. Verify context artifacts are current
3. Mark first task as `[~]`
4. Begin TDD workflow

### Completing a Phase

1. Ensure all phase tasks are `[x]`
2. Complete verification tasks
3. Wait for checkpoint approval
4. Record checkpoint SHA
5. Proceed to next phase

### Completing a Track

1. Verify all phases complete
2. Verify all acceptance criteria met
3. Update product.md if needed
4. Mark track completed in tracks.md
5. Update metadata.json

### Reverting a Track

1. Run `/conductor:revert`
2. Select track to revert
3. Choose granularity (track/phase/task)
4. Confirm revert operation
5. Update status markers

## Best Practices

1. **One track, one concern**: Keep tracks focused on a single logical change
2. **Small phases**: 3-5 tasks per phase maximum
3. **Verification after phases**: Always include verification tasks
4. **Update markers immediately**: Mark task status as you work
5. **Record SHAs**: Always note commit SHAs for completed tasks
6. **Review specs before planning**: Ensure spec is complete before creating plan
7. **Link dependencies**: Explicitly note track dependencies → see `references/dependencies-guide.md`
8. **Archive, don't delete**: Preserve completed tracks for reference
9. **Size appropriately**: 1-5 days of work per track → see `references/track-patterns.md`
10. **Clear acceptance criteria**: Every requirement must be testable
