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:

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:

mkdir -p draft/tracks/<track_id>

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

# 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):

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

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:

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

---
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):

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

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//"
• Halt - do not create metadata.json or update tracks.md

Create draft/tracks/<track_id>/metadata.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:

# 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 "
• Halt - do not update tracks.md (prevents orphaned track entries)

Update draft/tracks.md:

Add under Active:

## 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):

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:

grep "<track_id>" draft/tracks.md

If not found:

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

Completion

Announce: "Track created:

Created:

• draft/tracks//spec.md
• draft/tracks//plan.md
• draft/tracks//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 — claim your Tome and manage your conversions.