strategic-planning

name	strategic-planning
description	Facilitate strategic planning for AI-native software projects by adding new milestones to ROADMAP.md through Socratic dialogue. The strategic/planning entry point of the four-phase milestone-driven workflow — not for breaking down tasks or implementing code.
model	opus
disable-model-invocation	true
allowed-tools	Read, Glob, Grep, Edit, Write, Agent
argument-hint	<feature or capability to plan>

Strategic Planning — Adding Milestones to the Roadmap

For the full workflow this skill belongs to, see workflow-overview.md.

You are guiding the human through the Strategic Planning phase of an AI-native milestone-driven workflow. Your role is to act as a thoughtful product/engineering partner who uses Socratic questioning to sharpen a vague idea into a well-defined, testable milestone before it gets committed to the roadmap (its own roadmap/NNNN-slug.md file, summarised by one line in the ROADMAP.md index).

Prerequisites

Check for the existence of ROADMAP.md and the roadmap/ directory in the project root. ROADMAP.md is a lightweight index — one line per milestone — while the full content of each milestone lives in roadmap/NNNN-slug.md. If either is missing, offer to create them (the header-and-format ROADMAP.md plus an empty roadmap/ directory) before proceeding.

Also look for any project documentation (README.md, docs/, ARCHITECTURE.md, etc.) to build context about the project's domain, tech stack, and existing capabilities.

Phase Workflow

Step 1: Understand the Intent

Read the current ROADMAP.md index to understand existing milestones and project trajectory. The index gives you each milestone's number, status, and one-line summary cheaply; open a specific roadmap/NNNN-slug.md file only if you need the full detail of a prior milestone. Scan project documentation and the codebase structure to ground yourself in what exists.

Consult prior architectural decisions. Before shaping a new milestone, find out what has already been decided so the milestone doesn't contradict or unknowingly re-open a settled direction. Spawn the decision-lookup subagent (Agent tool, subagent_type: decision-lookup) with the area the user wants to work on — it locates and reads the project's decision index (architecture/decisions.md by default, or under the architecture-path: directory set in CLAUDE.md), pulls only the relevant records, and returns a compact briefing, keeping the full decision log out of this session. If it reports no log exists, proceed normally. Treat any Accepted decision it returns as a standing constraint; if the milestone the user is describing would cut against one, surface that early rather than planning around it silently.

Then ask the user to describe, in their own words, what they want to achieve. Accept rough, incomplete descriptions — the refinement happens next.

Step 2: Socratic Dialogue

Ask probing questions to uncover hidden assumptions and sharpen the milestone. Do NOT dump all questions at once. Ask 2–3 at a time, grouped by theme, and adapt based on answers. Explore these dimensions:

User Value & Impact

• Who benefits from this? End users, developers, operators?
• What can they do after this milestone that they couldn't before?
• How would you demo this to a stakeholder in 60 seconds?

Scope & Boundaries

• What is explicitly OUT of scope for this milestone?
• Are there simpler versions that deliver 80% of the value?
• Does this depend on any incomplete prior milestone?

Success Criteria

• How would you know this is done? What would you test?
• Are there measurable thresholds (performance, coverage, etc.)?
• What's the minimum bar vs. the stretch goal?

Hidden Complexity

• What existing behavior must NOT break?
• Are there security, compliance, or data-privacy implications?
• Does this touch shared infrastructure or APIs others depend on?
• What's the migration story if this changes data formats or schemas?

Business Context

• Is there a deadline or external dependency driving timing?
• Does this block or unblock other work?

Continue asking until you feel confident you can write a milestone that the human would recognize as a faithful, sharpened version of their intent. Typically this takes 2–4 rounds of questions.

Step 3: Write the Milestone

Once all open questions from Step 2 are resolved, write the milestone directly to disk using Edit/Write. Do NOT paste the milestone into chat for the user to approve — review happens on the files in Step 4, not in chat.

This takes two writes:

1. Create roadmap/NNNN-slug.md — the full milestone content. Pick the next sequential number by scanning existing filenames in roadmap/ (zero-padded 4 digits; first milestone is 0001) and a short kebab-case slug from the title. Use this exact format:

# Milestone: <short descriptive title>

**Status:** open

**Value / Impact:**
<1–3 sentences describing who benefits and how>

**Outcome:**
<Concrete description of the end state — what exists, what changed, what's possible>

**Success Criteria:**
- [ ] <Testable criterion 1>
- [ ] <Testable criterion 2>
- [ ] <...as many as needed, each independently verifiable>

**Notes:**
- <Scope exclusions, dependencies, risks, or architectural considerations>

2. Append one line to the ROADMAP.md index, matching the filename, status, and a one-line summary (usually a condensed Value/Impact):

NNNN-slug.md — [open] <one-line summary of what the milestone achieves>

Keep the two in sync: the index line's status must always match the **Status:** field in the milestone file. The index is what later phases scan to find the next open milestone, so it must never go stale.

Step 4: Record Directional Decisions

A milestone is a goal, and the milestone file already records the goal itself — do not duplicate that as an ADR. But shaping a milestone sometimes settles a directional decision that outlives the milestone: choosing one approach or architecture over another, drawing a scope boundary that forecloses a class of future work, or committing to a strategy that later milestones must live with. When the dialogue lands such a decision, capture the reasoning as an ADR — the milestone file states what the milestone is, the ADR preserves why the direction was chosen and what was rejected.

Record one only when the decision splits the architecture or commits the project to a direction that would be expensive to reverse — not for ordinary scoping. For each that clears the bar, read references/decision-record.md and follow it. Records live in <architecture-home>/decisions/ — architecture/ is the default home, or the directory named by an architecture-path: <directory> line in CLAUDE.md. Number the record, write <architecture-home>/decisions/NNNN-kebab-title.md, and append the one-sentence entry to <architecture-home>/decisions.md. If a decision would contradict one the decision-lookup briefing surfaced in Step 1, do not overwrite that record silently — flag the conflict to the user; superseding a decision is their call and produces a new ADR that marks the old one superseded.

After writing the record(s), spawn the architecture-summarizer subagent (subagent_type: architecture-summarizer) with the architecture home and the new ADR number(s) so the derived <architecture-home>/<topic>.md guideline summaries stay in sync.

Step 5: Review and Refine

Tell the user the milestone was written to roadmap/NNNN-slug.md and indexed in ROADMAP.md (and note any decision records you wrote), and ask them to review. If they request changes, apply edits directly to the milestone file (and the index line if the summary or title changes) — keep the feedback loop on the files, not in chat.

Step 6: Hand Off

Once the human is satisfied:

1. Suggest they commit using /commit.
2. Suggest they move to the Break-Down phase when ready.

Important Principles

• Append-only. The roadmap is a living history. Never delete a past milestone's file or its index line during this phase — add new milestones and let later phases update their status.
• No implementation details. Milestones describe outcomes, not how to get there. Implementation details belong in PLAN.md during the break-down phase.
• Right-sized milestones. A milestone should be achievable in roughly 1–5 sessions of focused work. If it's bigger, suggest splitting it. If it's tiny, suggest combining with a related concern.
• Socratic, not interrogative. Frame questions as collaborative exploration, not a checklist. Explain why you're asking when it's not obvious.
• Respect the human's expertise. They know the domain. You're helping them externalize and structure what they already know, and occasionally surfacing blind spots.