manual_slop/.claude/commands/conductor-new-track.md

---
description: Initialize a new conductor track with spec, plan, and metadata
---

# /conductor-new-track

Create a new track in the conductor system. This is a Tier 1 (Orchestrator) operation.
The quality of the spec and plan directly determines whether Tier 3 workers can execute
without confusion. Vague specs produce vague implementations.

## Prerequisites
- Read `conductor/product.md` and `conductor/product-guidelines.md` for product alignment
- Read `conductor/tech-stack.md` for technology constraints
- Consult architecture docs in `docs/` when the track touches core systems:
  - `docs/guide_architecture.md`: Threading, events, AI client, HITL mechanism
  - `docs/guide_tools.md`: MCP tools, Hook API, ApiHookClient
  - `docs/guide_mma.md`: Tickets, tracks, DAG engine, worker lifecycle
  - `docs/guide_simulations.md`: Test framework, mock provider, verification patterns

## Steps

### 1. Gather Information
Ask the user for:
- **Track name**: descriptive, snake_case (e.g., `add_auth_system`)
- **Track type**: `feat`, `fix`, `refactor`, `chore`
- **Description**: one-line summary
- **Requirements**: functional requirements for the spec

### 2. MANDATORY: Deep Codebase Audit

**This step is what separates useful specs from useless ones.**

Before writing a single line of spec, you MUST audit the actual codebase to understand
what already exists. Use the Research-First Protocol:

1. **Map the target area**: Use `py_get_code_outline` on every file the track will touch.
   Identify existing functions, classes, and their line ranges.
2. **Read key implementations**: Use `py_get_definition` on functions that are relevant
   to the track's goals. Understand their signatures, data structures, and control flow.
3. **Search for existing work**: Use `Grep` to find symbols, patterns, or partial
   implementations that may already address some requirements.
4. **Check recent changes**: Use `get_git_diff` on target files to understand what's
   been modified recently and by which tracks.

**Output of this step**: A "Current State Audit" section listing:
- What already exists (with file:line references)
- What's missing (the actual gaps this track fills)
- What's partially implemented and needs enhancement

### 3. Create Track Directory
```
conductor/tracks/{track_name}_{YYYYMMDD}/
```
Use today's date in YYYYMMDD format.

### 4. Create metadata.json
```json
{
  "track_id": "{track_name}_{YYYYMMDD}",
  "type": "{feat|fix|refactor|chore}",
  "status": "new",
  "created_at": "{ISO8601}",
  "updated_at": "{ISO8601}",
  "description": "{description}"
}
```

### 5. Create index.md
```markdown
# Track {track_name}_{YYYYMMDD} Context

- [Specification](./spec.md)
- [Implementation Plan](./plan.md)
- [Metadata](./metadata.json)
```

### 6. Create spec.md — The Surgical Specification

The spec MUST include these sections:

```markdown
# Track Specification: {Title}

## Overview
{What this track delivers and WHY — 2-3 sentences max}

## Current State Audit (as of {latest_commit_sha})
### Already Implemented (DO NOT re-implement)
- **{Feature}** (`{function_name}`, {file}:{lines}): {what it does}
- ...

### Gaps to Fill (This Track's Scope)
1. **{Gap}**: {What's missing, with reference to where it should go}
2. ...

## Goals
{Numbered list — crisp, no fluff}

## Functional Requirements
### {Requirement Group}
- {Specific requirement referencing actual data structures, function names, dict keys}
- ...

## Non-Functional Requirements
- Thread safety constraints (reference guide_architecture.md if applicable)
- Performance targets
- No new dependencies unless justified

## Architecture Reference
- {Link to relevant docs/guide_*.md section}

## Out of Scope
- {Explicit exclusions}
```

**Critical rules for specs:**
- NEVER describe a feature to implement without first checking if it exists
- ALWAYS include the "Current State Audit" section with line references
- ALWAYS link to relevant architecture docs
- Reference actual variable names, dict keys, and class names from the codebase

### 7. Create plan.md — The Surgical Plan

Each task must be specific enough that a Tier 3 worker on a lightweight model
can execute it without needing to understand the overall architecture.

```markdown
# Implementation Plan: {Title}

Architecture reference: [docs/guide_architecture.md](../../docs/guide_architecture.md)

## Phase 1: {Phase Name}
Focus: {One-sentence scope}

- [ ] Task 1.1: {SURGICAL description — see rules below}
- [ ] Task 1.2: ...
- [ ] Task 1.N: Write tests for {what Phase 1 changed}
- [ ] Task 1.X: Conductor - User Manual Verification (Protocol in workflow.md)
```

**Rules for writing tasks:**

1. **Reference exact locations**: "In `_render_mma_dashboard` (gui_2.py:2700-2701)"
   not "in the dashboard."
2. **Specify the API**: "Use `imgui.progress_bar(value, ImVec2(-1, 0), label)`"
   not "add a progress bar."
3. **Name the data**: "Read from `self.mma_streams` dict, keys prefixed with `'Tier 3'`"
   not "display the streams."
4. **Describe the change shape**: "Replace the single text box with four collapsible sections"
   not "improve the display."
5. **State thread safety**: "Push via `_pending_gui_tasks` with lock" when the task
   involves cross-thread data.
6. **For bug fixes**: List specific root cause candidates with code-level reasoning,
   not "investigate and fix."
7. **Each phase ends with**: A test task and a verification task.

### 8. Commit
```
conductor(track): Initialize track '{track_name}'
```

## Anti-Patterns (DO NOT do these)

- **Spec that describes features without checking if they exist** → produces duplicate work
- **Task that says "implement X" without saying WHERE or HOW** → worker guesses wrong
- **Plan with no line references** → worker wastes tokens searching
- **Spec with no architecture doc links** → worker misunderstands threading/data model
- **Tasks scoped too broadly** → worker tries to do too much, fails
- **No "Current State Audit"** → entire track may be re-implementing existing code

## Important
- Do NOT start implementing — track initialization only
- Implementation is done via `/conductor-implement`
- Each task should be scoped for a single Tier 3 Worker delegation