diff --git a/commands/start-planning.md b/commands/start-planning.md index 2d5db4f5f..76bd3bb45 100644 --- a/commands/start-planning.md +++ b/commands/start-planning.md @@ -39,7 +39,25 @@ Which discussion would you like to create a plan for? Ask: **Which discussion would you like to plan?** -## Step 3: Choose Output Destination +## Step 3: Choose Planning Path + +Ask: **Do you want to create a draft plan first, or proceed directly to formal planning?** + +**Path A: Draft Planning** +- Use when: Source materials need enrichment or filtering +- Creates `draft-plan.md` to build the specification collaboratively +- After draft is signed off, proceed to formal planning + +**Path B: Formal Planning** +- Use when: Source materials already contain complete specification +- Go straight to creating phases and tasks + +If user chooses Path A, skip to Step 5 (invoke skill with draft planning). +If user chooses Path B, continue to Step 4. + +## Step 4: Choose Output Destination + +*Skip this step if doing draft planning (Path A).* Ask: **Where should this plan live?** @@ -60,7 +78,7 @@ Ask: **Where should this plan live?** **If Linear or Backlog.md selected**: Check if MCP is available. If not, inform the user and suggest alternatives. -## Step 4: Gather Additional Context +## Step 5: Gather Additional Context **For Linear destination**: - Which team should own this project? @@ -69,30 +87,36 @@ Ask: **Where should this plan live?** - Any additional context or priorities to consider? - Any constraints since the discussion concluded? -## Step 5: Invoke Planning Skill +## Step 6: Invoke Planning Skill Pass to the technical-planning skill: - Discussion path: `docs/specs/discussions/{topic-name}/` -- Output destination: (local-markdown | linear | backlog-md) +- Planning path: (draft | formal) +- Output destination: (local-markdown | linear | backlog-md) - only if formal - Additional context gathered -Example handoff: +**Example handoff for Path A (Draft)**: +``` +Planning session for: {topic-name} +Discussion: docs/specs/discussions/{topic-name}/discussion.md +Path: Draft planning + +Begin planning using the technical-planning skill. +Reference: draft-planning.md +``` + +**Example handoff for Path B (Formal)**: ``` Planning session for: {topic-name} Discussion: docs/specs/discussions/{topic-name}/discussion.md +Path: Formal planning Output destination: Linear Team: Engineering Begin planning using the technical-planning skill. -Reference: output-linear.md for output format. +Reference: formal-planning.md, then output-linear.md ``` -The skill will: -1. Read the discussion document -2. Create phases and tasks -3. Output in the specified format -4. Create `plan.md` with appropriate frontmatter format - ## Notes - Ask questions clearly and wait for responses before proceeding diff --git a/skills/technical-planning/SKILL.md b/skills/technical-planning/SKILL.md index be341327d..1f76da869 100644 --- a/skills/technical-planning/SKILL.md +++ b/skills/technical-planning/SKILL.md @@ -5,156 +5,48 @@ description: "Transform technical discussion documents into actionable implement # Technical Planning -Act as **expert technical architect** translating discussion decisions into TDD-ready implementation plans. Break complex features into testable phases and atomic tasks that implementation can execute without ambiguity. +Act as **expert technical architect**, **product owner**, and **plan documenter**. Collaborate with the user to translate discussion decisions into actionable implementation plans. -Convert discussion docs into implementation plans. Output location depends on chosen destination. +Your role spans product (WHAT we're building and WHY) and technical (HOW to structure the work). -## Output Destinations +## You Must Ask Before Proceeding -Plans can be stored in different formats depending on user preference. You will be told which destination to use (typically via the `start-planning` command). +**If you don't know which path to take, ask the user.** -| Destination | Best For | Output | -|-------------|----------|--------| -| **Local Markdown** | Simple features, solo work | Single `plan.md` file | -| **Linear** | Team collaboration, visual tracking | Linear project + local pointer | -| **Backlog.md** | Local Kanban with MCP support | Task files in `backlog/` | +There are two paths: +- **Path A**: Draft planning first, then formal planning +- **Path B**: Formal planning directly -Reference the appropriate adapter for output format: -- **[output-local-markdown.md](references/output-local-markdown.md)** - Single plan.md file -- **[output-linear.md](references/output-linear.md)** - Linear project with labeled issues -- **[output-backlog-md.md](references/output-backlog-md.md)** - Backlog.md Kanban format +The user decides. If they haven't told you, ask: +> "Should we create a draft plan first to work through the details, or proceed directly to formal planning?" -**Default**: If no destination specified, use local markdown. +## Path A: Draft Planning -The planning *approach* is the same regardless of destination. Only the output format changes. +User wants to build the specification collaboratively before creating the formal plan. -## Four-Phase Workflow +**Load**: [draft-planning.md](references/draft-planning.md) -1. **Discussion** (previous): WHAT and WHY - decisions, architecture, edge cases -2. **Planning** (YOU): HOW - phases, tasks, acceptance criteria -3. **Implementation** (next): DOING - strict TDD execution of your plan -4. **Review** (final): VALIDATING - check work against decisions and plan +**Output**: `draft-plan.md` - standalone specification -You're at step 2. Don't implement. +**When complete**: User signs off, then proceed to Path B. -## Draft Planning for Complex Features +## Path B: Formal Planning -For complex or deeply technical work, planning itself requires discussion. Figuring out phases and tasks IS a conversation that needs capturing. +User wants to create the formal implementation plan (directly, or after draft). -**Two-phase planning**: -1. **Draft Planning**: Back-and-forth about structure, captured in `draft-plan.md` -2. **Formal Planning**: Convert draft to structured `plan.md` (or Linear/Backlog.md) +**Load**: [formal-planning.md](references/formal-planning.md) -See **[planning-conversations.md](references/planning-conversations.md)** for the draft planning workflow. - -**When to use draft planning**: -- Complex features with unclear phase boundaries -- Deeply technical work requiring back-and-forth -- Multiple valid ways to structure the work - -**Skip to formal planning when**: -- Structure is obvious from discussion doc -- Small feature with clear phases - -## Capture Planning Conversations Immediately - -> **After each user response, IMMEDIATELY update the planning document before asking your next question. Capture the user's exact words and reasoning, not summaries.** - -Context windows refresh without warning. Hours of planning discussion can vanish. - -**Capture frequency**: -- Update after every natural break in discussion -- Never let more than 2-3 exchanges pass without writing -- When in doubt, write it down NOW - -**What to capture**: -- What the user said AND why, not just conclusions -- Trade-offs considered and rejected -- Scope decisions with reasoning -- The journey, not just the destination - -## Commit Frequently - -**Commit planning docs often** to `docs/specs/plans/{topic-name}/`: - -- After each significant exchange -- At natural breaks in planning discussion -- When phases/tasks become clearer -- **Before any context refresh** -- When creating new files - -**Why**: You lose memory on context refresh. Commits prevent losing hours of planning work. This is non-negotiable. - -## You Create Plans, NOT Code - -**Your job**: Write plan document with phases, tasks, and acceptance criteria -**NOT your job**: Implement it, modify files, write production code - -## Phase > Task Hierarchy - -Plans use a two-level structure: - -``` -Phase (higher level) -├── Goal: What this phase accomplishes -├── Acceptance Criteria: How we know the phase is complete -└── Tasks (granular work units) - ├── Task 1: Description + micro acceptance + edge cases - ├── Task 2: Description + micro acceptance - └── Task 3: Description + micro acceptance -``` - -**Phase**: Independently testable unit. Has acceptance criteria. -**Task**: Single TDD cycle. One task = one test = one commit. - -## Plan Contents - -Use **[template.md](references/template.md)**: -- Phases with acceptance criteria -- Tasks with micro acceptance criteria (specific test that proves completion) -- Code examples for complex patterns -- Edge case handling from discussion -- Testing strategy -- Rollback plan +**Then load output adapter** (ask user which format): +- [output-local-markdown.md](references/output-local-markdown.md) - Single `plan.md` file (default) +- [output-linear.md](references/output-linear.md) - Linear project +- [output-backlog-md.md](references/output-backlog-md.md) - Backlog.md tasks ## Critical Rules -**Do**: -- Create phases with clear acceptance criteria -- Break phases into TDD-sized tasks -- Reference discussion rationale -- Make each task independently testable - -**Don't**: -- Write production code -- Modify project files -- Execute the plan -- Re-debate decisions - -## How Implementation Uses Your Plan - -Implementation will: -1. Read your plan -2. For each phase, announce start and review acceptance criteria -3. For each task, derive test from micro acceptance, write failing test, implement, commit -4. Verify phase acceptance criteria before proceeding -5. Ask user before starting next phase - -**Your plan quality determines implementation success.** - -## Reference Files - -**Planning approach**: -- **[planning-conversations.md](references/planning-conversations.md)** - Draft planning for complex features -- **[planning-approach.md](references/planning-approach.md)** - Workflow, step-by-step -- **[guidelines.md](references/guidelines.md)** - Best practices, task sizing -- **[template.md](references/template.md)** - Plan document template (for local markdown) +**Capture immediately**: After each user response, update the planning document BEFORE your next question. Never let more than 2-3 exchanges pass without writing. -**Output adapters** (use based on chosen destination): -- **[output-local-markdown.md](references/output-local-markdown.md)** - Single plan.md file -- **[output-linear.md](references/output-linear.md)** - Linear project integration -- **[output-backlog-md.md](references/output-backlog-md.md)** - Backlog.md Kanban format +**Commit frequently**: Commit at natural breaks, after significant exchanges, and before any context refresh. Context refresh = lost work. -## Remember +**Never invent reasoning**: If it's not in the document, ask again. -You're the architect, not the builder. Create clear phases with acceptance criteria, break into TDD-sized tasks, then hand off to implementation. +**Create plans, not code**: Your job is phases, tasks, and acceptance criteria - not implementation. diff --git a/skills/technical-planning/references/draft-planning.md b/skills/technical-planning/references/draft-planning.md new file mode 100644 index 000000000..23e65ad88 --- /dev/null +++ b/skills/technical-planning/references/draft-planning.md @@ -0,0 +1,146 @@ +# Draft Planning + +*Reference for **[technical-planning](../SKILL.md)** - Path A* + +--- + +You are creating a draft plan. The user has directed you here because the source materials need enrichment or filtering before formal planning can begin. + +## Purpose + +Draft planning produces a **standalone specification** - everything needed to construct formal phases and tasks. It is NOT a summary. It is NOT conversation notes. + +**Two purposes**: + +1. **Enrichment**: Source materials capture WHAT and WHY but need more detail on HOW, constraints, edge cases. Add this through collaborative discussion. + +2. **Filtering**: Source materials contain noise, tangents, speculation, or hallucinated content. Remove this through collaborative review. + +Most drafts involve both. + +## Output + +Create `draft-plan.md` in `docs/specs/plans/{topic-name}/` + +## Critical Rules + +**Capture immediately**: After each user response, update the draft document BEFORE your next question. Never let more than 2-3 exchanges pass without writing. + +**Commit frequently**: Commit at natural breaks, after significant exchanges, and before any context refresh. Context refresh = lost work. + +**Never invent reasoning**: If it's not in the document, ask again. + +## Draft Document Format + +The draft has two sections: **Planning Log** (running capture) and **Specification** (the deliverable). + +```markdown +# Draft Plan: [Topic Name] + +**Status**: Draft - building specification +**Created**: [date] +**Last Updated**: [timestamp] + +--- + +## Specification + +This section is the deliverable. Update it continuously as clarity emerges. + +### What We're Building + +[Specific, concrete description. What does it do? What problem does it solve?] + +### Why We're Building It + +[The motivation. What need does this address?] + +### Approach (Optional) + +[Include when there's a specific approach to follow. Leave light when implementation should figure it out.] + +### Scope Boundaries + +**In scope**: +- [Specific item] + +**Out of scope**: +- [Item and why excluded] + +### Technical Decisions + +| Decision | Choice | Reasoning | +|----------|--------|-----------| +| [decision point] | [what we chose] | [why] | + +### Edge Cases to Handle + +- [Edge case that implementation must handle] + +### Constraints + +- [Technical or business constraint] + +### Testing and Acceptance + +How we'll know this is complete: +- [Acceptance criterion] + +Testing ideas: +- [Test scenario] + +### Open Questions (Blocking) + +- [ ] [Question that MUST be answered before formal planning] + +--- + +## Planning Log + +Running capture of discussion. Use this to build the Specification above. + +### [timestamp] [Topic] + +[What was discussed, decisions made, reasoning.] +``` + +## The Specification is the Deliverable + +The Planning Log is working notes. The Specification section is what matters. + +As you discuss: +1. Capture in the Planning Log +2. **Immediately** distill validated information into the Specification +3. The Specification grows more complete with each exchange + +## What to Capture + +Record **what the user said AND why**, not just conclusions. + +Capture: +- Trade-offs considered +- Alternatives rejected and why +- Concerns raised and how addressed +- Scope decisions (in/out and why) + +## Transitioning to Formal Planning + +Draft is complete when the Specification contains: +- [ ] Clear WHAT and WHY +- [ ] Scope boundaries (in/out) +- [ ] Edge cases to handle +- [ ] Testing ideas and acceptance criteria +- [ ] Approach guidance (if needed) +- [ ] No blocking open questions + +**Transition**: +1. Review the Specification with user +2. User confirms it's complete +3. Proceed to formal planning → Load [formal-planning.md](formal-planning.md) +4. Keep `draft-plan.md` for reference + +## After Context Refresh + +If the draft exists: Read it. Trust it. The Specification has detail you've lost. + +If no draft exists: You've lost the conversation. Be honest and ask again. diff --git a/skills/technical-planning/references/formal-planning.md b/skills/technical-planning/references/formal-planning.md new file mode 100644 index 000000000..1002e4588 --- /dev/null +++ b/skills/technical-planning/references/formal-planning.md @@ -0,0 +1,126 @@ +# Formal Planning + +*Reference for **[technical-planning](../SKILL.md)** - Path B* + +--- + +You are creating the formal implementation plan. This is either: +- Direct from source materials (discussion docs), OR +- After completing draft planning (from `draft-plan.md`) + +## Before You Begin + +**Confirm output format with user.** Plans can be stored as: +- **Local Markdown** → See [output-local-markdown.md](output-local-markdown.md) +- **Linear** → See [output-linear.md](output-linear.md) +- **Backlog.md** → See [output-backlog-md.md](output-backlog-md.md) + +If you don't know which format, ask. + +## The Planning Process + +### 1. Read Source Material + +From discussion docs or draft plan, extract: +- Key decisions and rationale +- Architectural choices +- Edge cases identified +- Constraints and requirements + +### 2. Define Phases + +Break into logical phases: +- Each independently testable +- Each has acceptance criteria +- Progression: Foundation → Core → Edge cases → Refinement + +### 3. Break Phases into Tasks + +Each task is one TDD cycle: +- One clear thing to build +- One test to prove it works + +### 4. Write Micro Acceptance + +For each task, name the test that proves completion. Implementation writes this test first. + +### 5. Address Every Edge Case + +Extract each edge case, create a task with micro acceptance. + +### 6. Add Code Examples (if needed) + +Only for novel patterns not obvious to implement. + +### 7. Review Against Source + +Verify: +- All decisions referenced +- All edge cases have tasks +- Each phase has acceptance criteria +- Each task has micro acceptance + +## Phase Design + +**Each phase should**: +- Be independently testable +- Have clear acceptance criteria (checkboxes) +- Provide incremental value + +**Progression**: Foundation → Core functionality → Edge cases → Refinement + +## Task Design + +**Each task should**: +- Be a single TDD cycle +- Have micro acceptance (specific test name) +- Do one clear thing + +**One task = One TDD cycle**: write test → implement → pass → commit + +## Plan as Source of Truth + +The plan IS the source of truth. Every phase, every task must contain all information needed to execute it. + +- **Self-contained**: Each task executable without external context +- **No assumptions**: Spell out the context, don't assume implementer knows it + +## Flagging Incomplete Tasks + +When information is missing, mark it clearly with `[needs-info]`: + +```markdown +### Task 3: Configure rate limiting [needs-info] + +**Do**: Set up rate limiting for the API endpoint +**Test**: `it throttles requests exceeding limit` + +**Needs clarification**: +- What's the rate limit threshold? +- Per-user or per-IP? +``` + +Planning is iterative. Create structure, flag gaps, refine. + +## Quality Checklist + +Before handing off to implementation: + +- [ ] Clear phases with acceptance criteria +- [ ] Each phase has TDD-sized tasks +- [ ] Each task has micro acceptance (test name) +- [ ] All edge cases mapped to tasks +- [ ] Gaps flagged with `[needs-info]` + +## Commit Frequently + +Commit planning docs at natural breaks, after significant progress, and before any context refresh. + +Context refresh = memory loss. Uncommitted work = lost work. + +## Output + +Load the appropriate output adapter for format-specific structure: +- [output-local-markdown.md](output-local-markdown.md) - Single plan.md file +- [output-linear.md](output-linear.md) - Linear project +- [output-backlog-md.md](output-backlog-md.md) - Backlog.md tasks diff --git a/skills/technical-planning/references/guidelines.md b/skills/technical-planning/references/guidelines.md deleted file mode 100644 index 361cfb702..000000000 --- a/skills/technical-planning/references/guidelines.md +++ /dev/null @@ -1,106 +0,0 @@ -# Planning Guidelines - -*Reference for **[technical-planning](../SKILL.md)*** - ---- - -## Core Principles - -### Plan as Source of Truth - -The plan (whether Linear issues, Backlog.md tasks, or local markdown) IS the source of truth. Every phase, every task must contain all information needed to execute it. - -- **Self-contained**: Each task should be executable without external context -- **Reference, don't depend**: OK to link discussion docs, but if they vanish the task should still make sense -- **No assumptions**: Don't assume implementer knows context - spell it out - -### No Hallucinations - -If you don't know something, don't guess. If the discussion is missing information: - -1. **Flag it explicitly** - use `needs-info` label or note in task description -2. **Don't block on it** - create the task anyway, mark what's missing -3. **Circle back later** - iterate over plans multiple times, adding detail progressively - -Planning is iterative. You don't need complete information on pass one. Create structure, flag gaps, refine. - -### After Context Refresh - -You have summaries, not nuance. The planning documents ARE the nuance. - -**If draft/plan documents exist**: Read them. Trust them. They have reasoning you've lost. - -**If no documents exist**: You've lost the planning conversation. Be honest. Don't pretend you remember details you don't have. - -**Never invent reasoning** that wasn't captured. If it's not in the document, ask again. - -### Immediate Capture - -> After each user response, IMMEDIATELY update the planning document before asking your next question. - -- Capture the user's exact words and reasoning, not summaries -- Never let more than 2-3 exchanges pass without writing -- Record what was said AND why, not just conclusions - -### Task Design - -- **One task = One TDD cycle**: write test → implement → pass → commit -- **Exact paths**: Specify exact file paths, not "update the controller" -- **Reference, don't re-debate**: "Using Redis (per discussion doc)" not re-debating -- **Test name required**: Every task needs a micro acceptance that becomes a test - -## Phase Design - -**Each phase should**: -- Be independently testable -- Have clear acceptance criteria (checkboxes) -- Provide incremental value - -**Good progression**: Foundation → Core functionality → Edge cases → Refinement - -## Task Design - -**Each task should**: -- Be a single TDD cycle -- Have micro acceptance (specific test name) -- Take 5-30 minutes -- Do one clear thing - -**Bad tasks**: "Implement caching layer" (too big), "Handle errors" (too vague) - -## Micro Acceptance - -The test name that proves task completion. Implementation will: -1. Read your micro acceptance -2. Write that test (failing) -3. Implement to pass -4. Commit - -**Your micro acceptance quality determines test quality.** - -## Edge Case Handling - -Extract each edge case from discussion. For each: -- Create a task with micro acceptance -- Assign to specific phase - -## Quality Checklist - -**Structure**: -- [ ] Clear phases with acceptance criteria -- [ ] Each phase has TDD-sized tasks -- [ ] Each task has micro acceptance (test name) - -**Self-Contained**: -- [ ] Each task executable without reading discussion doc -- [ ] No assumed context - everything spelled out -- [ ] Links to discussion for "why", but task has the "what" and "how" - -**Content**: -- [ ] All edge cases from discussion mapped to tasks -- [ ] No hallucinations - unknown info flagged with `needs-info` -- [ ] Gaps identified explicitly, not glossed over - -**Iteration**: -- [ ] OK if first pass incomplete - flag and refine -- [ ] Can circle back multiple times before implementation diff --git a/skills/technical-planning/references/output-local-markdown.md b/skills/technical-planning/references/output-local-markdown.md index cc5e9e2df..01c71fa94 100644 --- a/skills/technical-planning/references/output-local-markdown.md +++ b/skills/technical-planning/references/output-local-markdown.md @@ -4,7 +4,7 @@ --- -Use this output format for **simple features** or when you want everything version-controlled in a single file. +Use this format for simple features or when you want everything in a single version-controlled file. ## Output Location @@ -13,11 +13,11 @@ docs/specs/plans/{topic-name}/ └── plan.md ``` -The directory name should match the discussion topic name from `docs/specs/discussions/{topic-name}/`. +Directory name should match the discussion topic from `docs/specs/discussions/{topic-name}/`. -## File Structure +## Template -Create `plan.md` with frontmatter declaring the format: +Create `plan.md` with this structure: ```markdown --- @@ -30,64 +30,124 @@ format: local-markdown **Status**: Draft | Ready | In Progress | Completed **Discussion**: `docs/specs/discussions/{topic-name}/` -... rest of plan content ... -``` +## Overview -Use the template from **[template.md](template.md)** for the full structure including: +**Goal**: What we're building and why (one sentence) -- Overview (goal, done-when, key decisions) -- Architecture summary -- Phases with acceptance criteria checkboxes -- Tasks with micro acceptance (test names) -- Edge case mapping table -- Testing strategy -- Dependencies -- Change log +**Done when**: +- Measurable outcome 1 +- Measurable outcome 2 -## Frontmatter +**Key Decisions** (from discussion): +- Decision 1: Rationale +- Decision 2: Rationale -The `format: local-markdown` frontmatter tells implementation that the full plan content is in this file. +## Architecture + +- Components +- Data flow +- Integration points + +## Phases + +Each phase is independently testable with clear acceptance criteria. +Each task is a single TDD cycle: write test → implement → commit. -```yaml --- -format: local-markdown + +### Phase 1: {Name} + +**Goal**: What this phase accomplishes + +**Acceptance**: +- [ ] Criterion 1 +- [ ] Criterion 2 + +**Tasks**: + +1. **{Task Name}** + - **Do**: What to implement + - **Test**: `"it does expected behavior"` + - **Edge cases**: (if any) + +2. **{Task Name}** + - **Do**: What to implement + - **Test**: `"it does expected behavior"` + --- -``` -## What to Include +### Phase 2: {Name} + +**Goal**: What this phase accomplishes + +**Acceptance**: +- [ ] Criterion 1 +- [ ] Criterion 2 + +**Tasks**: + +1. **{Task Name}** + - **Do**: What to implement + - **Test**: `"it does expected behavior"` + +(Continue pattern for remaining phases) + +--- + +## Edge Cases + +Map edge cases from discussion to specific tasks: + +| Edge Case | Solution | Phase.Task | Test | +|-----------|----------|------------|------| +| {From discussion} | How handled | 1.2 | `"it handles X"` | + +## Testing Strategy + +**Unit**: What to test per component +**Integration**: What flows to verify +**Manual**: (if needed) + +## Data Models (if applicable) + +Tables, schemas, API contracts + +## Dependencies + +- Prerequisites for Phase 1 +- Phase dependencies +- External blockers + +## Rollback (if applicable) -Everything goes in the single `plan.md` file: +Triggers and steps -- All phases and tasks inline -- All acceptance criteria -- Edge case mapping -- Code examples for complex patterns +## Log + +| Date | Change | +|------|--------| +| YYYY-MM-DD | Created from discussion | +``` + +## Frontmatter + +The `format: local-markdown` frontmatter tells implementation that the full plan content is in this file. ## Flagging Incomplete Tasks -When creating tasks with missing information, mark them clearly: +When information is missing, mark clearly with `[needs-info]`: ```markdown ### Task 3: Configure rate limiting [needs-info] **Do**: Set up rate limiting for the API endpoint +**Test**: `it throttles requests exceeding limit` -**Micro acceptance**: `it throttles requests exceeding limit` - -**⚠️ Needs clarification**: +**Needs clarification**: - What's the rate limit threshold? - Per-user or per-IP? ``` -Use `[needs-info]` suffix in task title. This allows iterative refinement - create the structure, flag gaps, circle back to discussion, update tasks. - -## When to Use - -- Small to medium features -- Solo development -- Quick iterations -- When you want simple git-tracked documentation - ## Resulting Structure After planning: @@ -102,4 +162,4 @@ docs/specs/ └── plan.md # format: local-markdown ``` -Implementation will read `plan.md`, see `format: local-markdown`, and execute directly from file content. +Implementation reads `plan.md`, sees `format: local-markdown`, and executes directly from file content. diff --git a/skills/technical-planning/references/planning-approach.md b/skills/technical-planning/references/planning-approach.md deleted file mode 100644 index 6cd41a547..000000000 --- a/skills/technical-planning/references/planning-approach.md +++ /dev/null @@ -1,89 +0,0 @@ -# Planning Approach - -*Reference for **[technical-planning](../SKILL.md)*** - ---- - -## Your Role - -Bridge between discussion and implementation. Convert decisions into executable plans. - -**You create**: Plans with phases, tasks, acceptance criteria -**You don't**: Implement, modify files, write production code, re-debate decisions - -## Workflow - -### 0. Draft Planning (For Complex Features) - -For complex or deeply technical work, the planning conversation itself needs capturing. - -**Before jumping to formal phases and tasks**: -1. Create `draft-plan.md` in the plans directory -2. Discuss structure with the user -3. Capture the conversation in real-time (see below) -4. Once structure is agreed, proceed to formal planning - -**Immediate capture rule**: After each user response, update the draft document BEFORE your next question. Never let 2-3 exchanges pass without writing. - -See **[planning-conversations.md](planning-conversations.md)** for full draft planning workflow. - -**Skip draft planning when**: Structure is obvious, small feature, user knows exactly what they want. - -### 1. Read Discussion Document - -From `docs/specs/discussions/{topic}/` extract: -- Key decisions and rationale -- Architectural choices -- Edge cases identified -- Constraints and requirements - -### 2. Define Phases - -Break into logical phases: -- Each independently testable -- Each has acceptance criteria -- Progression: Foundation → Core → Edge cases → Refinement - -### 3. Break Phases into Tasks - -Each task is one TDD cycle: -- One clear thing to build -- One test to prove it works -- 5-30 minutes of work - -### 4. Write Micro Acceptance - -For each task, name the test that proves completion. -Implementation will write this test first. - -### 5. Address Every Edge Case - -From discussion: extract each edge case, create a task with micro acceptance. - -### 6. Add Code Examples (if needed) - -Only for novel patterns not obvious to implement. Show structure, not production code. - -### 7. Review Against Discussion - -Verify: -- All decisions referenced -- All edge cases have tasks -- Each phase has acceptance criteria -- Each task has micro acceptance - -## Output - -Create `docs/specs/plans/{topic-name}/plan.md` using [template.md](template.md). - -Implementation can execute via strict TDD without going back to discussion. - -## Commit Frequently - -Commit planning docs at: -- After each significant exchange during draft planning -- At natural breaks in discussion -- When phases/tasks become clearer -- **Before any context refresh** - -Context refresh = memory loss. Uncommitted work = lost work. diff --git a/skills/technical-planning/references/planning-conversations.md b/skills/technical-planning/references/planning-conversations.md deleted file mode 100644 index 50a6b22c4..000000000 --- a/skills/technical-planning/references/planning-conversations.md +++ /dev/null @@ -1,188 +0,0 @@ -# Planning Conversations - -*Reference for **[technical-planning](../SKILL.md)*** - ---- - -## The Problem - -Planning complex features requires discussion. Figuring out what phases and tasks should exist IS a conversation - and that conversation can be lost to context window refresh just like any other. - -**Lost context = lost nuance**. A summary after refresh contains conclusions, not the reasoning. The "why we structured it this way" is gone. - -## Two-Phase Planning - -For complex or deeply technical work, planning happens in two phases: - -### Phase A: Draft Planning (Capture) - -A back-and-forth conversation about structure: -- What phases make sense? -- How should we break this down? -- What order? What dependencies? -- What's the scope of each task? - -**Output**: `draft-plan.md` - running log of the planning conversation - -### Phase B: Formal Planning (Organize) - -Convert draft into structured format: -- Phases with acceptance criteria -- Tasks with micro acceptance -- Ready for implementation - -**Output**: `plan.md` (or Linear/Backlog.md depending on destination) - -## When to Use Draft Planning - -**Use draft planning when**: -- Complex feature with unclear phase boundaries -- Deeply technical work requiring back-and-forth -- Multiple valid ways to structure the work -- User wants to think through the approach together - -**Skip to formal planning when**: -- Structure is obvious from discussion doc -- Small feature with clear phases -- User already knows exactly how they want it structured - -## Critical Rule: Immediate Capture - -> **After each user response, IMMEDIATELY update the draft document before asking your next question.** - -This is non-negotiable. Context windows refresh without warning. Three hours of planning discussion can vanish. - -### Capture Frequency - -- Update after **every natural break** in discussion -- **Never let more than 2-3 exchanges pass** without writing -- When in doubt, write it down NOW - -### What to Capture - -Record **what the user said AND why**, not just conclusions: - -**Bad**: "Phase 1 will handle authentication" - -**Good**: "User wants auth first because: (1) everything depends on knowing who the user is, (2) can't test other features without login working, (3) existing auth is partially broken and blocking current work" - -### Capture the Reasoning Journey - -- Why this phase before that one -- Trade-offs considered -- Alternative structures rejected and why -- Concerns raised and how addressed -- Scope decisions (what's in, what's out, why) - -## Draft Document Format - -Use a running log format. Raw capture first, organize later. - -```markdown -# Draft Plan: [Topic Name] - -**Status**: Draft - capturing planning discussion -**Created**: [date] -**Last Updated**: [timestamp] - ---- - -## Planning Log - -### [timestamp] Initial Structure Discussion - -User wants to start with [X] because [reasoning]. - -Considered starting with [Y] instead, but [why rejected]. - -Key constraint: [what limits our options]. - -### [timestamp] Phase Breakdown - -Discussing how to split the work: - -**Option A**: [description] -- Pro: [benefit] -- Con: [drawback] - -**Option B**: [description] -- Pro: [benefit] -- Con: [drawback] - -User leaning toward Option A because [specific reasoning]. - -### [timestamp] Task Granularity - -For Phase 1, user wants tasks like: -- [task idea] - reasoning: [why this granularity] -- [task idea] - concern: [what might be tricky] - -Discussed whether [X] should be one task or two. Decision: [outcome] because [why]. - -### [timestamp] Dependencies and Order - -[Y] must come before [Z] because [specific dependency]. - -User noted that [A] and [B] could be parallel since [reasoning]. - ---- - -## Emerging Structure - -(Update this as structure becomes clear) - -### Phase 1: [Name] -- Goal: [what this accomplishes] -- Tasks identified so far: - - [ ] [task] - - [ ] [task] - -### Phase 2: [Name] -- Goal: [what this accomplishes] -- Depends on: Phase 1 because [why] -- Tasks identified so far: - - [ ] [task] - ---- - -## Open Questions - -- [ ] [question still being discussed] -- [ ] [decision not yet made] - -## Decisions Made - -- [decision]: [reasoning captured] -``` - -## Commit Frequently - -**Commit the draft document**: -- After each significant exchange -- At natural breaks in discussion -- When structure becomes clearer -- **Before any context refresh** -- When creating the initial file - -Commits are your safety net. A context refresh with uncommitted work = lost work. - -## Transitioning to Formal Plan - -When draft planning is complete: - -1. Review the draft document together -2. User confirms the emerging structure -3. Create formal `plan.md` using the [template](template.md) -4. Keep `draft-plan.md` for reference (the "why we structured it this way") - -The draft captures the journey. The formal plan captures the destination. - -## Anti-Hallucination - -After context refresh, you have summaries, not nuance. The draft document IS the nuance. - -**If the draft exists**: Read it. Trust it. It has the reasoning you've lost. - -**If no draft exists**: You've lost the planning conversation. Be honest about this. Don't pretend you remember details you don't have. - -**Never invent reasoning** that wasn't captured. If it's not in the document, ask again. diff --git a/skills/technical-planning/references/template.md b/skills/technical-planning/references/template.md deleted file mode 100644 index bd7ee1e4c..000000000 --- a/skills/technical-planning/references/template.md +++ /dev/null @@ -1,149 +0,0 @@ -# Implementation Plan Template - -*Part of **[technical-planning](../SKILL.md)** | See also: **[planning-approach.md](planning-approach.md)** · **[guidelines.md](guidelines.md)*** - ---- - -## Template - -```markdown ---- -format: local-markdown ---- - -# Implementation Plan: {Feature/Project Name} - -**Date**: YYYY-MM-DD -**Status**: Draft | Ready | In Progress | Completed -**Discussion**: `docs/specs/discussions/{topic-name}/` - -## Overview - -**Goal**: What we're building and why (one sentence) - -**Done when**: -- Measurable outcome 1 -- Measurable outcome 2 - -**Key Decisions** (from discussion): -- Decision 1: Rationale -- Decision 2: Rationale - -## Architecture - -- Components -- Data flow -- Integration points - -## Phases - -Each phase is independently testable with clear acceptance criteria. -Each task is a single TDD cycle: write test → implement → commit. - ---- - -### Phase 1: {Name} - -**Goal**: What this phase accomplishes - -**Acceptance**: -- [ ] Criterion 1 -- [ ] Criterion 2 - -**Tasks**: - -1. **{Task Name}** - - **Do**: What to implement - - **Test**: `"it does expected behavior"` - - **Edge cases**: (if any) - -2. **{Task Name}** - - **Do**: What to implement - - **Test**: `"it does expected behavior"` - ---- - -### Phase 2: {Name} - -**Goal**: What this phase accomplishes - -**Acceptance**: -- [ ] Criterion 1 -- [ ] Criterion 2 - -**Tasks**: - -1. **{Task Name}** - - **Do**: What to implement - - **Test**: `"it does expected behavior"` - -(Continue pattern for remaining phases) - ---- - -## Edge Cases - -Map edge cases from discussion to specific tasks: - -| Edge Case | Solution | Phase.Task | Test | -|-----------|----------|------------|------| -| {From discussion} | How handled | 1.2 | `"it handles X"` | - -## Testing Strategy - -**Unit**: What to test per component -**Integration**: What flows to verify -**Manual**: (if needed) - -## Data Models (if applicable) - -Tables, schemas, API contracts - -## Dependencies - -- Prerequisites for Phase 1 -- Phase dependencies -- External blockers - -## Rollback (if applicable) - -Triggers and steps - -## Log - -| Date | Change | -|------|--------| -| YYYY-MM-DD | Created from discussion | -``` - -## How to Create a Plan - -1. Start with the discussion document -2. Extract key decisions and architecture choices -3. Identify logical phases (each independently testable) -4. Break each phase into TDD-sized tasks -5. Add test name for each task -6. Map edge cases from discussion to specific tasks - -## Sizing - -**Phase**: Independently testable, verifiable completion - -**Task**: One TDD cycle (test → implement → commit), ~5-30 min - -**Too big**: "Implement caching layer" (multiple TDD cycles) -**Too vague**: "Handle errors" (no testable criteria) - -## Ready for Implementation - -- [ ] Each phase has acceptance criteria -- [ ] Each task has a test name -- [ ] Edge cases mapped to tasks -- [ ] Dependencies identified - -## What to Avoid - -- Tasks too big for a single TDD cycle -- Vague acceptance criteria -- Missing edge case coverage -- Re-debating decisions already made in discussion