# New Track

> Start a new feature or bug track. Collaborative intake process with structured questions, AI guidance, and progressive refinement before generating spec.md and plan.md. Use when this capability is needed.

- Skill: `tomevault-io/new-track` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/new-track`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/new-track/raw
- Safety review: pending (external: skill-scanner PASS, skillspector WARNING)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/new-track

---


# Create New Track

You are creating a new track (feature, bug fix, or refactor) for Context-Driven Development. This is a **collaborative process** — you are an active participant providing guidance, fact-checking, and expertise grounded in vetted sources.

**Feature Description:** $ARGUMENTS

## Red Flags - STOP if you're:

- Creating a track without reading existing Draft context (product.md, tech-stack.md, .ai-context.md)
- Asking questions without contributing expertise or trade-off analysis
- Rushing through intake without probing deeper with "why"
- Generating spec/plan without user confirmation at checkpoints
- Skipping risk identification
- Not citing sources when giving architectural advice

**Collaborative understanding, not speed.**

---

## Pre-Check

1. Verify Draft is initialized:
```bash
ls draft/product.md draft/tech-stack.md draft/workflow.md draft/tracks.md 2>/dev/null
```

If missing, tell user: "Project not initialized. Run `/draft:init` first."

2. Check for `--quick` flag in `$ARGUMENTS`:
   - If present: **strip `--quick` from `$ARGUMENTS` now** (before Step 1) and store the cleaned text as the working description for all subsequent steps. Proceed to Step 1, then go directly to **Step 1.5: Quick Mode**.
   - Quick mode is for: hotfixes, tiny isolated changes, work scoped to 1-3 hours

3. Load full project context (these documents ARE the big picture — every track must be grounded in them):
- Read `draft/product.md` — product vision, users, goals, constraints, guidelines (optional section)
- Read `draft/tech-stack.md` — languages, frameworks, patterns, code style, accepted patterns
- Read `draft/.ai-context.md` (if exists) — system map, modules, data flows, invariants, security architecture. Falls back to `draft/architecture.md` for legacy projects.
- Read `draft/workflow.md` — TDD preference, commit conventions, review process
- Read `draft/guardrails.md` (if exists) — hard guardrails, learned conventions, learned anti-patterns
- Read `draft/tracks.md` — existing tracks to check for overlap or dependencies

4. Load guidance references:
- Read `core/templates/intake-questions.md` — structured questions for intake
- Read `core/knowledge-base.md` — vetted sources for AI guidance

## Step 1: Generate Track ID

Create a short, kebab-case ID from the description (use the stripped description if `--quick` was present):
- "Add user authentication" → `add-user-auth`
- "Fix login bug" → `fix-login-bug`

If the description is empty (e.g., `--quick` with no text), ask the user: "What should this track be called? (brief description)"

Check if `draft/tracks/<track_id>/` already exists. If collision detected, append `-<ISO-date>` suffix (e.g., `feature-auth-2026-02-21`). If the suffixed path also exists, append `-2`, `-3`, etc. until a free path is found.

### Branch Creation (Toolchain-Aware)

Read `draft/workflow.md` → `## Toolchain` section to determine VCS mode:
- **git mode:** `git checkout -b <track_id>`
- **cot mode with Jira ticket:** `cot checkout -t <JIRA_ID> -s <track_id>`
- **cot mode without Jira ticket:** `cot checkout <track_id>`

If no toolchain section found, default to git mode.

## Step 1.5: Quick Mode Path (`--quick` only)

**Skip if:** `--quick` was not present in `$ARGUMENTS`.

Skip all intake conversation. Ask only two questions:

1. "What exactly needs to change? (1-2 sentences)"
2. "How will you know it's done? (list acceptance criteria)"

Then create the track directory and generate both files directly:

```bash
mkdir -p draft/tracks/<track_id>
```

**`draft/tracks/<track_id>/spec.md`** (minimal — no YAML frontmatter needed):

```markdown
# Spec: [Title]

**Track ID:** <track_id>
**Type:** quick

## What

[description from question 1]

## Acceptance Criteria

- [ ] [from question 2, one per line]

## Non-Goals

- No scope expansion beyond what's described above
```

**`draft/tracks/<track_id>/plan.md`** (flat — single phase, no phases ceremony):

```markdown
# Plan: [Title]

**Track ID:** <track_id>

## Phase 1: Complete

**Goal:** [one-line summary from spec]
**Verification:** [how to confirm ACs are met — run tests / manual check]

### Tasks

- [ ] **Task 1:** [derived from AC 1]
- [ ] **Task N:** Verify — [run tests or check from AC]
```

Then execute **Step 8** (Create Metadata & Update Tracks) with these overrides for quick tracks:
- `"type": "quick"` (not `feature|bugfix|refactor`)
- `"phases": {"total": 1, "completed": 0}` (plan has exactly 1 phase)

Skip Steps 2–7.

After Step 8 completes, announce:
```
Quick track created: <track_id>

Files: spec.md (minimal), plan.md (flat)
Next: /draft:implement
```

---

## Step 2: Create Draft Files

Create the track directory and draft files immediately with skeleton structure:

```bash
mkdir -p draft/tracks/<track_id>
```

### Create `draft/tracks/<track_id>/spec-draft.md`:

**MANDATORY: Include YAML frontmatter with git metadata.** Gather git info first:

```bash
git branch --show-current 2>/dev/null || git rev-parse --short HEAD 2>/dev/null || echo "none"  # LOCAL_BRANCH
git rev-parse --abbrev-ref @{upstream} 2>/dev/null || echo "none"  # REMOTE/BRANCH
git rev-parse HEAD 2>/dev/null || echo "none"                      # FULL_SHA
git rev-parse --short HEAD 2>/dev/null || echo "none"              # SHORT_SHA
git log -1 --format=%ci HEAD 2>/dev/null || echo "none"            # COMMIT_DATE
git log -1 --format=%s HEAD 2>/dev/null || echo "none"             # COMMIT_MESSAGE
git status --porcelain 2>/dev/null | head -1 | wc -l               # 0 = clean, >0 = dirty
```

```markdown
---
project: "{PROJECT_NAME}"
module: "root"
track_id: "<track_id>"
generated_by: "draft:new-track"
generated_at: "{ISO_TIMESTAMP}"
git:
  branch: "{LOCAL_BRANCH}"
  remote: "{REMOTE/BRANCH}"
  commit: "{FULL_SHA}"
  commit_short: "{SHORT_SHA}"
  commit_date: "{COMMIT_DATE}"
  commit_message: "{COMMIT_MESSAGE}"
  dirty: {true|false}
synced_to_commit: "{FULL_SHA}"
---

# Specification Draft: [Title]

| Field | Value |
|-------|-------|
| **Branch** | `{LOCAL_BRANCH}` → `{REMOTE/BRANCH}` |
| **Commit** | `{SHORT_SHA}` — {COMMIT_MESSAGE} |
| **Generated** | {ISO_TIMESTAMP} |
| **Synced To** | `{FULL_SHA}` |

**Track ID:** <track_id>
**Status:** [ ] Drafting

> This is a working draft. Content will evolve through conversation.

## Context References
- **Product:** `draft/product.md` — [pending]
- **Tech Stack:** `draft/tech-stack.md` — [pending]
- **Architecture:** `draft/.ai-context.md` — [pending]

## Problem Statement
[To be developed through intake conversation]

## Background & Why Now
[To be developed through intake conversation]

## Requirements
### Functional
[To be developed through intake conversation]

### Non-Functional
[To be developed through intake conversation]

## Acceptance Criteria
[To be developed through intake conversation]

## Non-Goals
[To be developed through intake conversation]

## Technical Approach
[To be developed through intake conversation]

## Success Metrics
<!-- Remove metrics that don't apply -->

| Category | Metric | Target | Measurement |
|----------|--------|--------|-------------|
| Performance | [e.g., API response time] | [e.g., <200ms p95] | [e.g., APM dashboard] |
| Quality | [e.g., Test coverage] | [e.g., >90%] | [e.g., CI coverage report] |
| Business | [e.g., User adoption rate] | [e.g., 50% in 30 days] | [e.g., Analytics] |
| UX | [e.g., Task completion rate] | [e.g., >95%] | [e.g., User testing] |

## Stakeholders & Approvals
<!-- Add roles relevant to your organization -->

| Role | Name | Approval Required | Status |
|------|------|-------------------|--------|
| Product Owner | [name] | Spec sign-off | [ ] |
| Tech Lead | [name] | Architecture review | [ ] |
| Security | [name] | Security review (if applicable) | [ ] |
| QA | [name] | Test plan review | [ ] |

### Approval Gates
- [ ] Spec approved by Product Owner
- [ ] Architecture reviewed by Tech Lead
- [ ] Security review completed (if touching auth, data, or external APIs)
- [ ] Test plan reviewed by QA

## Risk Assessment
<!-- Score: Probability (1-5) × Impact (1-5). Risks scoring ≥9 require mitigation plans. -->

| Risk | Probability | Impact | Score | Mitigation |
|------|-------------|--------|-------|------------|
| [e.g., Third-party API instability] | 3 | 4 | 12 | [e.g., Circuit breaker + fallback cache] |
| [e.g., Data migration failure] | 2 | 5 | 10 | [e.g., Dry-run migration + rollback script] |
| [e.g., Scope creep] | 3 | 3 | 9 | [e.g., Strict non-goals enforcement] |

## Deployment Strategy
<!-- Define rollout approach for production delivery. For bug fixes and minor refactors, this section may be removed or marked N/A. -->

### Rollout Phases
1. **Canary** (1-5% traffic) — Validate core flows, monitor error rates
2. **Limited GA** (25%) — Expand to subset, watch performance metrics
3. **Full GA** (100%) — Complete rollout

### Feature Flags
- Flag name: `[feature_flag_name]`
- Default: `off`
- Kill switch: [yes/no]

### Rollback Plan
- Trigger: [e.g., error rate >1%, latency >500ms p95]
- Process: [e.g., disable feature flag, revert deployment]
- Data rollback: [e.g., migration revert script, N/A]

### Monitoring
- Dashboard: [link or name]
- Alerts: [e.g., PagerDuty rule for error rate spike]
- Key metrics: [e.g., error rate, latency, throughput]

## Open Questions
[Tracked during conversation]

## Conversation Log
> Key decisions and reasoning captured during intake.

[Conversation summary will be added here]
```

### Create `draft/tracks/<track_id>/plan-draft.md`:

**MANDATORY: Include YAML frontmatter with git metadata** (same git info as spec-draft.md):

```markdown
---
project: "{PROJECT_NAME}"
module: "root"
track_id: "<track_id>"
generated_by: "draft:new-track"
generated_at: "{ISO_TIMESTAMP}"
git:
  branch: "{LOCAL_BRANCH}"
  remote: "{REMOTE/BRANCH}"
  commit: "{FULL_SHA}"
  commit_short: "{SHORT_SHA}"
  commit_date: "{COMMIT_DATE}"
  commit_message: "{COMMIT_MESSAGE}"
  dirty: {true|false}
synced_to_commit: "{FULL_SHA}"
---

# Plan Draft: [Title]

| Field | Value |
|-------|-------|
| **Branch** | `{LOCAL_BRANCH}` → `{REMOTE/BRANCH}` |
| **Commit** | `{SHORT_SHA}` — {COMMIT_MESSAGE} |
| **Generated** | {ISO_TIMESTAMP} |
| **Synced To** | `{FULL_SHA}` |

**Track ID:** <track_id>
**Spec:** ./spec.md
**Status:** [ ] Drafting

> This is a working draft. Phases will be defined after spec is finalized.

## Overview
[To be developed after spec finalization]

## Phases
[To be developed after spec finalization]

## Notes
[Tracked during conversation]
```

Announce: "Created draft files. Let's build out the specification through conversation."

---

## Step 3: Collaborative Intake

Follow the structured intake from `core/templates/intake-questions.md`. You are an **active collaborator**, not just a questioner.

### Your Role as AI Collaborator

For each question:
1. **Ask** the question clearly
2. **Listen** to the user's response
3. **Contribute** your expertise:
   - Pattern recognition from industry experience
   - Trade-off analysis with citations from knowledge-base.md
   - Risk identification the user may not see
   - Fact-checking against project context (.ai-context.md, tech-stack.md)
   - Alternative approaches with pros/cons
4. **Update** spec-draft.md with what's been established
5. **Summarize** periodically: "Here's what we have so far..."

### Citation Style

Ground advice in vetted sources:
- "Consider CQRS here (DDIA, Ch. 11) — separates read/write concerns."
- "This could violate the Dependency Rule (Clean Architecture)."
- "Circuit breaker pattern (Release It!) would help prevent cascade failures."
- "Watch for OWASP A01:2021 — Broken Access Control."

### Red Flags - STOP if you're:

- Asking questions without contributing expertise
- Accepting answers without probing deeper with "why"
- Not citing sources when giving architectural advice
- Skipping risk identification
- Not updating drafts as conversation progresses
- Rushing toward generation instead of understanding
- Not referencing product.md, tech-stack.md, .ai-context.md

**The goal is collaborative understanding, not speed.**

---

## Step 3A: Intake Flow (Feature / Refactor)

### Phase 1: Existing Documentation
- "Do you have existing documentation for this work? (PRD, RFC, design doc, Jira ticket)"
- If yes: Ingest, extract key points, identify gaps
- AI contribution: "I've extracted [X, Y, Z]. I notice [gap] isn't covered yet."

### Phase 2: Problem Space
Walk through problem questions from intake-questions.md:
- What problem are we solving?
- Why does this problem matter now?
- Who experiences this pain?
- What's the scope boundary?

After each answer:
- Contribute relevant patterns, similar problems, domain concepts
- Challenge assumptions with "why" questions
- Update spec-draft.md Problem Statement section

**Checkpoint:** "Here's the problem as I understand it: [summary]. Does this capture it?"

### Phase 3: Solution Space
Walk through solution questions:
- What's the simplest version that solves this?
- Why this approach over alternatives?
- What are we explicitly NOT doing?
- How does this fit with current architecture?

After each answer:
- Present 2-3 alternative approaches with trade-offs
- Cross-reference .ai-context.md (or architecture.md) for integration points
- Suggest tech-stack.md patterns to leverage
- Update spec-draft.md Technical Approach and Non-Goals sections

**Checkpoint:** "The proposed approach is [summary]. I've identified these alternatives: [list]. Your reasoning for this choice is [X]. Correct?"

### Phase 4: Risk & Constraints
Walk through risk questions:
- What could go wrong?
- What dependencies or blockers exist?
- Why might this fail?
- Security or compliance considerations?

After each answer:
- Surface risks user may not have considered
- Reference OWASP, distributed systems fallacies, failure modes
- Fact-check assumptions against project context
- Update spec-draft.md with risks as Open Questions

**Checkpoint:** "Key risks identified: [list]. Are there others you're aware of?"

### Phase 5: Success Criteria
Walk through success questions:
- How do we know this is complete?
- How will we verify it works?
- What would make stakeholders accept this?

After each answer:
- Suggest measurable, testable acceptance criteria
- Recommend testing strategies appropriate to feature type
- Align with product.md goals
- Update spec-draft.md Acceptance Criteria section

**Checkpoint:** "Acceptance criteria so far: [list]. Missing anything?"

### Step 3A.5: Cross-Skill Integration

At this point, check for cross-skill dispatch opportunities:

**Refactor Tracks → Tech-Debt Offer:**
If track type is "refactor" (detected from description keywords: refactor, clean up, reorganize, migrate, upgrade):
```
"Run `/draft:tech-debt` to scope this refactor before writing the spec? [Y/n]"
```
- If accepted: run tech-debt analysis, feed findings into spec scope section
- If declined: proceed with manual scoping

**Design Decision Detection → ADR Suggestion:**
If the spec involves any of: new technology adoption, architectural boundary changes, API redesign, data model changes:
- Suggest: "This involves a significant design decision. Run `/draft:adr` to document it? [Y/n]"

---

## Step 3B: Intake Flow (Bug & RCA)

For bugs, incidents, or Jira-sourced issues. Tighter scope, investigation-focused.

### Phase 1: Symptoms & Context
- "What's the exact error or unexpected behavior?"
- "Who is affected? How often does this occur?"
- "When did this start? Any recent changes?"

AI contribution: Pattern recognition for common bug types, severity assessment.

### Phase 2: Reproduction
- "What are the exact steps to reproduce?"
- "What environment conditions are required?"
- "What's the expected vs actual behavior?"

AI contribution: Suggest additional reproduction scenarios, edge cases to check.

### Phase 3: Blast Radius
- "What still works correctly?"
- "Where does the failure boundary lie?"

AI contribution: Help narrow investigation scope, reference architecture.md for module boundaries.

### Phase 4: Code Locality
- "Where do you suspect the bug is?"
- "What's the entry point and failure point?"

AI contribution: Suggest investigation approach, reference debugging patterns.

Update spec-draft.md with bug-specific structure after gathering sufficient context.

### Step 3B.5: Auto-Triage Pipeline

For bug tracks, execute this automated triage pipeline:

**Trigger:** Track type is bug/RCA AND any of: Jira ticket ID found, description contains "incident", "outage", "SEV", "regression", "crash".

If trigger conditions not met, skip to Step 4.

1. **Gather External Context:**
   - If Jira ticket provided: pull via MCP (`get_issue()`, `get_issue_description()`, `get_issue_comments()`)
   - Extract URLs, log paths, stack traces, reproduction steps, affected services
   - Use `curl`/`wget` to fetch any URLs mentioned (dashboards, error pages, API responses)
   - Use `ssh` to access log locations on remote nodes (if paths like `/home/log/`, node IPs mentioned)

2. **Offer Debug Session:**
   "Run `/draft:debug` to investigate before writing the spec? [Y/n]"
   - If accepted: launch debug session, feed findings back into spec
   - If declined: proceed with spec generation from available context

3. **RCA Analysis (if sufficient context):**
   - Apply 5 Whys methodology (reference `core/agents/rca.md`)
   - Classify root cause type
   - Assess blast radius using `.ai-context.md` module boundaries

4. **Generate rca.md:**
   - Save to `draft/tracks/<id>/rca.md` using `core/templates/rca.md` template
   - This feeds into `/draft:implement` as investigation context

5. **Jira Sync:**
   - If ticket linked: attach rca.md and post comment via `core/shared/jira-sync.md`

6. **Developer Checkpoint:**
   "Root cause hypothesis: [summary]. Blast radius: [scope]. Proceed with spec generation? [Y/n]"
   - "Want me to write regression tests for this? [Y/n]"

### Step 3B.6: Incident Context Detection

Check if incident keywords detected in description (outage, incident, P0, SEV1, production down):
- If postmortem exists: load as context for spec generation
- Suggest: "Consider running `/draft:incident-response postmortem` for formal post-incident analysis"

---

## Step 4: Draft Review & Refinement

After completing intake sections:

1. Present complete spec-draft.md summary
2. List any remaining Open Questions
3. Ask: "Want to refine any section, or ready to finalize?"

If refining:
- Continue conversation on specific sections
- Update drafts as discussion progresses
- Return to this step when ready

---

## Step 4.5: Elicitation Pass

Before finalizing, offer a quick spec stress-test. This takes 2 minutes and often surfaces blind spots.

Based on the track type (feature / bug / refactor), present 3 pre-selected challenge techniques:

**Feature tracks:**
1. **Pre-mortem** — "It's 6 months later and this feature failed. What went wrong?"
2. **Scope Boundary** — "What's the smallest version that still achieves the core goal?"
3. **Edge Case Storm** — Surface 5 boundary conditions not yet in the ACs

**Bug tracks:**
1. **Root Cause Depth** — "Is the reported symptom the real bug, or a symptom of something deeper?"
2. **Blast Radius** — "What else could this fix inadvertently break?"
3. **Regression Risk** — "What existing behavior might this change inadvertently affect?"

**Refactor tracks:**
1. **Behavior Preservation** — "List every externally visible behavior that must be identical before and after"
2. **Integration Impact** — "Which callers will break if this interface changes?"
3. **Rollback Complexity** — "If this refactor needs reverting mid-flight, what's the path?"

Present to the user:

```
Quick stress-test before finalizing — pick one or skip:

1. [Technique name] — [one-line prompt]
2. [Technique name] — [one-line prompt]
3. [Technique name] — [one-line prompt]

Enter 1–3, or "skip":
```

- **If a number is chosen:** Apply that technique to the current spec-draft.md. Show what it reveals. Update spec-draft.md if findings are significant (new ACs, revised non-goals, added risks).
- **If "skip":** Proceed directly to Step 5. No friction.

---

## Step 5: Finalize Specification

When user confirms spec is ready:

1. Finalize `spec-draft.md` → `spec.md`:
   1. Read `spec-draft.md` content.
   2. Write content to `spec.md`.
   3. Verify `spec.md` exists and has non-empty content.
   4. Delete `spec-draft.md`.
2. Update `spec.md` status to `[x] Complete`
3. Update Context References with specific connections to product.md, tech-stack.md, .ai-context.md
4. Add Conversation Log summary with key decisions and reasoning

Present final spec.md for acknowledgment.

---

## Step 6: Create Plan

Based on finalized spec, build out plan-draft.md:

### For Feature / Refactor:
Create phased breakdown:
- Phase 1: Foundation / Setup
- Phase 2: Core Implementation
- Phase 3: Integration & Polish

For each phase:
- Define Goal and Verification criteria
- Break into specific Tasks with file references
- Identify dependencies between tasks

AI contribution:
- Suggest task ordering based on dependencies
- Reference tech-stack.md for implementation patterns
- Identify testing requirements per task
- Flag integration points with .ai-context.md modules

### For Bug & RCA:
Use fixed 3-phase structure:
- Phase 1: Investigate & Reproduce
- Phase 2: Root Cause Analysis
- Phase 3: Fix & Verify

Reference `core/agents/rca.md` for detailed process.

Present plan-draft.md for review.

---

## Step 7: Finalize Plan

When user confirms plan is ready:

1. Update plan-draft.md status to `[x] Complete`
2. Write final content to `plan.md`, then delete `plan-draft.md`
3. Validate phases against spec requirements
4. Ensure all acceptance criteria are covered by tasks

Present final plan.md for acknowledgment.

---

## Step 8: Create Metadata & Update Tracks

### Pre-Validation

Before creating metadata, verify final files exist:

```bash
ls draft/tracks/<track_id>/spec.md draft/tracks/<track_id>/plan.md 2>/dev/null
```

If either missing:
- ERROR: "Track creation incomplete. Missing files: [list missing]"
- "Expected: spec.md and plan.md in draft/tracks/<track_id>/"
- Halt - do not create metadata.json or update tracks.md

### Create `draft/tracks/<track_id>/metadata.json`:

```json
{
  "id": "<track_id>",
  "title": "[Title]",
  "type": "feature|bugfix|refactor",
  "status": "planning",
  "created": "[ISO timestamp]",
  "updated": "[ISO timestamp]",
  "phases": {
    "total": 3,
    "completed": 0
  },
  "tasks": {
    "total": "<count all `- [ ]` task lines in plan.md>",
    "completed": 0
  }
}
```

Count all `- [ ]` task lines in `plan.md` and set `tasks.total` in `metadata.json` accordingly instead of 0.

**Note:** ISO timestamps can use either `Z` or `.000Z` suffix (both valid ISO 8601). No format constraint enforced — both second precision (`2026-02-08T12:00:00Z`) and millisecond precision (`2026-02-08T12:00:00.000Z`) are acceptable.

### Verify metadata.json

Before updating tracks.md, verify metadata.json was written successfully:

```bash
# Validate JSON (try python3 first, fall back to node, then jq)
cat draft/tracks/<track_id>/metadata.json | python3 -c "import sys,json; json.load(sys.stdin)" 2>/dev/null \
  || node -e "JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'))" < draft/tracks/<track_id>/metadata.json 2>/dev/null \
  || jq . draft/tracks/<track_id>/metadata.json >/dev/null 2>&1 \
  || echo "INVALID"
```

If invalid or missing:
- ERROR: "Failed to write valid metadata.json for track <track_id>"
- Halt - do not update tracks.md (prevents orphaned track entries)

### Update `draft/tracks.md`:

Add under Active:

```markdown
## Active

### [track_id] - [Title]
- **Status:** [ ] Planning
- **Created:** [date]
- **Phases:** 0/3
- **Path:** `./tracks/<track_id>/`
```

### Cleanup (Defensive)

Remove draft files if they still exist (defensive cleanup for failed renames):

```bash
rm -f draft/tracks/<track_id>/spec-draft.md
rm -f draft/tracks/<track_id>/plan-draft.md
```

The `-f` flag ensures idempotent cleanup whether files exist or not.

### Post-Validation

Verify tracks.md was updated successfully:

```bash
grep "<track_id>" draft/tracks.md
```

If not found:
- ERROR: "Failed to update tracks.md with new track entry"
- "Expected track_id '<track_id>' in draft/tracks.md Active section"
- Provide recovery: "Manually add track entry to draft/tracks.md or remove draft/tracks/<track_id>/ and retry"

---

## Completion

Announce:
"Track created: <track_id>

Created:
- draft/tracks/<track_id>/spec.md
- draft/tracks/<track_id>/plan.md
- draft/tracks/<track_id>/metadata.json

Updated:
- draft/tracks.md

Key decisions documented in spec.md Conversation Log.

Next: Review the spec and plan, then run `/draft:implement` to begin."

## Cross-Skill Dispatch

### Conditional Plan Tasks
When generating plan.md, auto-embed these tasks based on context:
- All tracks: add "Run `/draft:testing-strategy`" task if no testing strategy exists
- Feature tracks with new APIs: add "Run `/draft:documentation api`" task
- All tracks: add "Run `/draft:deploy-checklist`" as a final pre-deployment verification task

### At Completion
- **Jira sync:** If ticket linked, attach spec.md and plan.md, post comment: "[draft] spec-complete: Specification and plan generated for track {id}" via `core/shared/jira-sync.md`
- **Bug tracks:** "Run `/draft:debug track {id}` to begin structured investigation"
- **Feature tracks:** "Review the spec and plan, then run `/draft:implement` to begin"
- If track scope is large or involves multiple modules: "Run `/draft:decompose` to break this into modules? [Y/n]"
- **Refactor tracks:** "Run `/draft:tech-debt` to catalog debt items before implementation"

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/mayurpise) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->