From 82eb34d1bf5304b8ef0836f5b758c5f6bcc92224 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 10 Dec 2025 20:36:26 +0000 Subject: [PATCH 01/11] Clarify draft planning as specification-building, not summarization The draft plan is a collaborative process to build a standalone specification that leaves implementation with zero creative latitude. Key clarifications: - Draft serves two purposes: enrichment (adding missing detail through collaboration) and filtering (removing noise/speculation/hallucination) - Output must be standalone - contains everything needed for formal planning - Anti-pattern: summaries that create "another useless file" - Good vs bad draft examples added with concrete detail - New "No Room for Creativity" principle in guidelines - Updated document format with Specification section as the deliverable --- skills/technical-planning/SKILL.md | 28 +- .../references/guidelines.md | 14 + .../references/planning-approach.md | 18 +- .../references/planning-conversations.md | 246 ++++++++++++------ 4 files changed, 216 insertions(+), 90 deletions(-) diff --git a/skills/technical-planning/SKILL.md b/skills/technical-planning/SKILL.md index be341327d..f1320c783 100644 --- a/skills/technical-planning/SKILL.md +++ b/skills/technical-planning/SKILL.md @@ -37,24 +37,34 @@ The planning *approach* is the same regardless of destination. Only the output f You're at step 2. Don't implement. -## Draft Planning for Complex Features +## Draft Planning: Building the Specification -For complex or deeply technical work, planning itself requires discussion. Figuring out phases and tasks IS a conversation that needs capturing. +Draft planning produces a **standalone specification** - a document containing everything needed to construct formal phases and tasks. It is NOT a summary. It is NOT conversation notes. + +**The draft serves two purposes**: + +1. **Enrichment**: Source materials may capture WHAT and WHY but not HOW. Draft planning adds missing detail through collaborative discussion (not hallucination). + +2. **Filtering**: Source materials may contain noise, tangents, speculation, or hallucinated content. Draft planning removes this through collaborative review. **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) +1. **Draft Planning**: Collaborate to build complete specification in `draft-plan.md` +2. **Formal Planning**: Structure the specification into phases/tasks + +See **[planning-conversations.md](references/planning-conversations.md)** for the full draft planning workflow. -See **[planning-conversations.md](references/planning-conversations.md)** for the draft planning workflow. +**The draft must leave no room for interpretation**. Implementation agents should have zero creative latitude - everything needed is spelled out. **When to use draft planning**: -- Complex features with unclear phase boundaries -- Deeply technical work requiring back-and-forth +- Source materials need enrichment (missing HOW details) +- Source materials need filtering (noise, speculation, hallucination) +- Complex features with unclear approach - Multiple valid ways to structure the work **Skip to formal planning when**: -- Structure is obvious from discussion doc -- Small feature with clear phases +- Source materials already contain complete specification +- Small feature with obvious structure +- All detail already worked out elsewhere ## Capture Planning Conversations Immediately diff --git a/skills/technical-planning/references/guidelines.md b/skills/technical-planning/references/guidelines.md index 361cfb702..4c0eb2a6f 100644 --- a/skills/technical-planning/references/guidelines.md +++ b/skills/technical-planning/references/guidelines.md @@ -14,6 +14,20 @@ The plan (whether Linear issues, Backlog.md tasks, or local markdown) IS the sou - **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 Room for Creativity + +Implementation agents (or humans) should have **zero creative latitude** when executing your plan. If they have to make decisions, your plan is incomplete. + +**Test**: Could someone execute this plan mechanically, without making judgment calls? + +**Bad**: "Add caching to improve performance" +- Implementer must decide: What to cache? TTLs? Cache keys? Invalidation strategy? + +**Good**: "Add Redis caching to /api/products endpoint. Key format: products:{id}. TTL: 300 seconds. Invalidate on Product model save event using cache tags." +- Implementer just executes. No decisions required. + +This level of detail comes from **draft planning** - collaborative discussion that builds a complete specification before formal phases/tasks are created. + ### No Hallucinations If you don't know something, don't guess. If the discussion is missing information: diff --git a/skills/technical-planning/references/planning-approach.md b/skills/technical-planning/references/planning-approach.md index 6cd41a547..a881380bf 100644 --- a/skills/technical-planning/references/planning-approach.md +++ b/skills/technical-planning/references/planning-approach.md @@ -13,21 +13,25 @@ Bridge between discussion and implementation. Convert decisions into executable ## Workflow -### 0. Draft Planning (For Complex Features) +### 0. Draft Planning (Building the Specification) -For complex or deeply technical work, the planning conversation itself needs capturing. +Draft planning produces a **standalone specification** containing everything needed for formal planning. This is NOT conversation notes or a summary. + +**The draft process**: +1. **Enrichment**: Add missing detail through collaborative discussion (not hallucination) +2. **Filtering**: Remove noise, speculation, and hallucinated content through collaborative review **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 +2. Collaborate with user to build the Specification section +3. Continue until specification is complete and unambiguous +4. Proceed to formal planning only when draft leaves no room for interpretation -**Immediate capture rule**: After each user response, update the draft document BEFORE your next question. Never let 2-3 exchanges pass without writing. +**Immediate capture rule**: After each user response, update the draft document BEFORE your next question. Distill validated information into the Specification section immediately. 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. +**Skip draft planning when**: Source materials already contain complete specification with all detail needed for implementation. ### 1. Read Discussion Document diff --git a/skills/technical-planning/references/planning-conversations.md b/skills/technical-planning/references/planning-conversations.md index 50a6b22c4..09b8746a2 100644 --- a/skills/technical-planning/references/planning-conversations.md +++ b/skills/technical-planning/references/planning-conversations.md @@ -4,29 +4,63 @@ --- -## The Problem +## The Purpose of Draft Planning -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. +Draft planning exists to produce a **standalone specification** containing everything needed to construct formal phases and tasks. It is NOT a summary. It is NOT conversation notes. It is the complete, unambiguous foundation for formal planning. -**Lost context = lost nuance**. A summary after refresh contains conclusions, not the reasoning. The "why we structured it this way" is gone. +The draft is where you collaborate with the user to ensure: +1. **Nothing is missing** - all detail required for implementation is present +2. **Nothing is hallucinated** - only real, validated information remains +3. **No room for interpretation** - implementation agents have zero creative latitude -## Two-Phase Planning +### Two Scenarios That Require Draft Planning + +**Scenario A: Enrichment (Adding Detail)** + +Source materials (discussion docs, etc.) may capture WHAT to build and WHY, but haven't fully rounded out HOW to approach it. The draft process adds this detail through collaborative discussion - not hallucination. + +- What's the actual sequence of work? +- What are the specific constraints? +- What patterns or approaches will we use? +- What edge cases need explicit handling? + +**Scenario B: Filtering (Removing Noise)** + +Source materials may contain too much detail, tangential discussion, speculative content, or hallucinated information. The draft process filters this through collaborative review. + +- What's actually in scope vs mentioned but not committed to? +- Which discussed options were rejected? +- What was speculation vs decision? +- What information is validated vs assumed? + +Most real planning involves **both** - enriching some areas while filtering others. -For complex or deeply technical work, planning happens in two phases: +### The Draft as Deliverable -### Phase A: Draft Planning (Capture) +At the end of draft planning, `draft-plan.md` must be a **standalone file** containing: +- Everything needed to construct formal phases/tasks +- Enough detail that implementation has no ambiguity +- Only validated information, not summaries or assumptions -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? +**Anti-pattern**: A draft that summarizes the discussion into three bullet points is useless. That's just another file with vague content that requires re-discovery. -**Output**: `draft-plan.md` - running log of the planning conversation +**Correct pattern**: A draft that captures specific decisions, specific approaches, specific constraints, specific edge cases - everything the formal plan needs spelled out. -### Phase B: Formal Planning (Organize) +## Two-Phase Planning + +### Phase A: Draft Planning (Build the Specification) + +Collaborative discussion that produces a complete specification: +- What exactly are we building? +- How exactly will we approach it? +- What specific constraints and edge cases exist? +- What's in scope, what's out? + +**Output**: `draft-plan.md` - standalone specification ready for structuring -Convert draft into structured format: +### Phase B: Formal Planning (Structure the Specification) + +Convert the complete draft into structured format: - Phases with acceptance criteria - Tasks with micro acceptance - Ready for implementation @@ -36,15 +70,16 @@ Convert draft into structured format: ## When to Use Draft Planning **Use draft planning when**: -- Complex feature with unclear phase boundaries -- Deeply technical work requiring back-and-forth +- Source materials need enrichment (missing HOW details) +- Source materials need filtering (contains noise, speculation, hallucination) +- Complex feature with unclear approach - Multiple valid ways to structure the work -- User wants to think through the approach together +- User wants to collaborate on the specification **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 +- Source materials already contain complete specification +- Small feature with obvious structure +- User has already worked out all the detail elsewhere ## Critical Rule: Immediate Capture @@ -76,84 +111,78 @@ Record **what the user said AND why**, not just conclusions: ## Draft Document Format -Use a running log format. Raw capture first, organize later. +The draft has two sections: a **Planning Log** (running capture) and a **Specification** (the deliverable). The log feeds the specification. ```markdown # Draft Plan: [Topic Name] -**Status**: Draft - capturing planning discussion +**Status**: Draft - building specification **Created**: [date] **Last Updated**: [timestamp] --- -## Planning Log - -### [timestamp] Initial Structure Discussion +## Specification -User wants to start with [X] because [reasoning]. +This section is the deliverable. Update it continuously as clarity emerges. -Considered starting with [Y] instead, but [why rejected]. +### What We're Building -Key constraint: [what limits our options]. +[Specific, concrete description - not a summary. Include enough detail that someone could understand the scope without reading source materials.] -### [timestamp] Phase Breakdown +### Approach -Discussing how to split the work: +[How we will build this. Specific patterns, sequences, constraints. Not "we'll handle errors" but "validation errors return 422 with field-level messages using the existing ValidationException handler".] -**Option A**: [description] -- Pro: [benefit] -- Con: [drawback] +### Scope Boundaries -**Option B**: [description] -- Pro: [benefit] -- Con: [drawback] +**In scope**: +- [Specific item with enough detail to be unambiguous] +- [Specific item] -User leaning toward Option A because [specific reasoning]. +**Out of scope** (explicitly excluded): +- [Item and why excluded] +- [Item] -### [timestamp] Task Granularity +### Technical Decisions -For Phase 1, user wants tasks like: -- [task idea] - reasoning: [why this granularity] -- [task idea] - concern: [what might be tricky] +| Decision | Choice | Reasoning | +|----------|--------|-----------| +| [decision point] | [what we chose] | [why - be specific] | -Discussed whether [X] should be one task or two. Decision: [outcome] because [why]. +### Edge Cases and Constraints -### [timestamp] Dependencies and Order +- [Specific edge case]: [how it will be handled] +- [Constraint]: [how it affects implementation] -[Y] must come before [Z] because [specific dependency]. +### Open Questions (Blocking) -User noted that [A] and [B] could be parallel since [reasoning]. +- [ ] [Question that MUST be answered before formal planning] --- -## Emerging Structure +## Planning Log -(Update this as structure becomes clear) +Running capture of discussion. Use this to build the specification above. -### Phase 1: [Name] -- Goal: [what this accomplishes] -- Tasks identified so far: - - [ ] [task] - - [ ] [task] +### [timestamp] Initial Discussion -### Phase 2: [Name] -- Goal: [what this accomplishes] -- Depends on: Phase 1 because [why] -- Tasks identified so far: - - [ ] [task] +[What was discussed, decisions made, reasoning. Use this to populate the Specification section above.] ---- +### [timestamp] [Topic] -## Open Questions +[Continue capturing. After each exchange, update BOTH this log AND the Specification section.] +``` -- [ ] [question still being discussed] -- [ ] [decision not yet made] +### Key Principle: The Specification Section is the Deliverable -## Decisions Made +The Planning Log is working notes. The Specification section is what matters. -- [decision]: [reasoning captured] -``` +As you discuss with the user: +1. Capture in the Planning Log +2. **Immediately** distill validated information into the Specification +3. The Specification grows more complete with each exchange +4. When Specification is complete, formal planning can begin ## Commit Frequently @@ -168,21 +197,90 @@ Commits are your safety net. A context refresh with uncommitted work = lost work ## Transitioning to Formal Plan -When draft planning is complete: +Draft planning is complete when the **Specification section** contains: +- [ ] Complete description of what we're building (no ambiguity) +- [ ] Specific approach with enough detail for implementation +- [ ] Clear scope boundaries (in/out) +- [ ] All technical decisions documented with reasoning +- [ ] All edge cases identified with handling approach +- [ ] No blocking open questions remaining + +**Transition process**: +1. Review the Specification section together +2. User confirms it contains everything needed +3. Create formal `plan.md` by structuring the Specification into phases/tasks +4. Keep `draft-plan.md` for reference (the "why" behind decisions) -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 Specification is standalone** - formal planning should not require going back to source discussion documents. Everything needed is in the draft. -The draft captures the journey. The formal plan captures the destination. +## Good Draft vs Bad Draft + +**Bad Draft** (creates no value): +```markdown +## What We're Building +A caching layer for the API. + +## Approach +We'll add Redis caching to improve performance. + +## Scope +- Add caching +- Handle invalidation +``` + +This is useless. It says nothing concrete. An implementation agent reading this would have to make everything up - cache keys, TTLs, what gets cached, invalidation strategy, error handling. + +**Good Draft** (enables formal planning): +```markdown +## What We're Building +Response caching for the /api/products endpoints. Cache full JSON responses +keyed by endpoint + query parameters. Target: reduce database load by 80% +for repeated identical requests. + +## Approach +- Use existing Redis connection from config/database.php +- Cache at controller level using Laravel's Cache facade +- Key format: "products:{endpoint}:{hash(query_params)}" +- TTL: 5 minutes for list endpoints, 15 minutes for single product +- Cache-Control headers: public, max-age matching TTL +- Invalidation: Tag-based using "products" tag, clear on any Product model event + +## Scope Boundaries +**In scope**: +- GET /api/products (list with filters) +- GET /api/products/{id} (single product) +- Cache warming not included in initial implementation + +**Out of scope**: +- POST/PUT/DELETE endpoints (no caching) +- User-specific data (cart, wishlist) - different caching strategy later +- CDN integration - separate initiative + +## Technical Decisions +| Decision | Choice | Reasoning | +|----------|--------|-----------| +| Cache location | Controller | Simpler than middleware, can make per-endpoint decisions | +| TTL strategy | Fixed per endpoint | Predictable, avoids complexity of adaptive TTLs | +| Invalidation | Tag-based | Product updates rare, tag clear is simple and sufficient | + +## Edge Cases +- Empty result sets: Cache them (prevents repeated DB hits for non-existent filters) +- Large responses (>1MB): Still cache, Redis handles it, revisit if memory issues +- Redis unavailable: Fail open, skip cache, log warning, don't break requests +``` + +The good draft leaves nothing to imagination. Implementation knows exactly what to build. ## Anti-Hallucination -After context refresh, you have summaries, not nuance. The draft document IS the nuance. +During draft planning, you are **building** the specification through discussion. Do not invent details - ask. + +**Do**: "The discussion mentions caching but doesn't specify TTLs. What cache duration makes sense for your use case?" -**If the draft exists**: Read it. Trust it. It has the reasoning you've lost. +**Don't**: Assume TTLs, cache keys, or strategies that weren't discussed. -**If no draft exists**: You've lost the planning conversation. Be honest about this. Don't pretend you remember details you don't have. +After context refresh: +- **If the draft exists**: Read it. Trust it. The Specification section has the detail you've lost. +- **If no draft exists**: 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. +**Never invent reasoning or detail** that wasn't captured. If it's not in the document, ask again. From 3f513902003e24593b976e0655b1abf51a4ab307 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 10 Dec 2025 21:18:01 +0000 Subject: [PATCH 02/11] Reframe draft planning as collaborative balance-finding, not constraint Key changes: - Remove "zero creative latitude" and "no room for interpretation" language - Draft captures WHAT/WHY/edge cases/acceptance - HOW is optional and varies - Amount of detail depends on the feature - some need detailed approach, others just need clear definition - Implementation can take charge or collaborate - not just mechanical execution - Good draft example now shows guidance without being prescriptive - Draft process is about finding the RIGHT level of detail, not maximum detail --- skills/technical-planning/SKILL.md | 2 +- .../references/guidelines.md | 22 ++-- .../references/planning-approach.md | 4 +- .../references/planning-conversations.md | 116 +++++++++++------- 4 files changed, 90 insertions(+), 54 deletions(-) diff --git a/skills/technical-planning/SKILL.md b/skills/technical-planning/SKILL.md index f1320c783..a75ea8d7c 100644 --- a/skills/technical-planning/SKILL.md +++ b/skills/technical-planning/SKILL.md @@ -53,7 +53,7 @@ Draft planning produces a **standalone specification** - a document containing e See **[planning-conversations.md](references/planning-conversations.md)** for the full draft planning workflow. -**The draft must leave no room for interpretation**. Implementation agents should have zero creative latitude - everything needed is spelled out. +**The draft captures** WHAT we're building, WHY, edge cases, and testing/acceptance criteria. HOW much detail to include varies - some features need detailed approach guidance, others just need clarity on what to build. The draft process is collaborative - together you find the right level of detail. **When to use draft planning**: - Source materials need enrichment (missing HOW details) diff --git a/skills/technical-planning/references/guidelines.md b/skills/technical-planning/references/guidelines.md index 4c0eb2a6f..9e877d81e 100644 --- a/skills/technical-planning/references/guidelines.md +++ b/skills/technical-planning/references/guidelines.md @@ -14,19 +14,27 @@ The plan (whether Linear issues, Backlog.md tasks, or local markdown) IS the sou - **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 Room for Creativity +### Finding the Right Level of Detail -Implementation agents (or humans) should have **zero creative latitude** when executing your plan. If they have to make decisions, your plan is incomplete. +The draft process is collaborative - together with the user, you figure out how much detail is needed for THIS feature. Some features need detailed HOW guidance; others just need clear WHAT/WHY and implementation can work out the approach. -**Test**: Could someone execute this plan mechanically, without making judgment calls? +**Always include**: +- WHAT we're building (specific, not vague) +- WHY we're building it (the motivation) +- Edge cases to be aware of +- Testing ideas and acceptance criteria + +**Include when helpful**: +- HOW to approach it (varies by feature complexity and team familiarity) +- Specific patterns or constraints **Bad**: "Add caching to improve performance" -- Implementer must decide: What to cache? TTLs? Cache keys? Invalidation strategy? +- Too vague. What endpoints? What's the goal? What edge cases? -**Good**: "Add Redis caching to /api/products endpoint. Key format: products:{id}. TTL: 300 seconds. Invalidate on Product model save event using cache tags." -- Implementer just executes. No decisions required. +**Good**: "Add caching to /api/products to reduce DB load. Target 80% fewer queries. Handle: empty results, large responses, Redis failures. Implementation can determine TTLs and key strategy." +- Clear WHAT and WHY. Edge cases identified. HOW left to implementation where appropriate. -This level of detail comes from **draft planning** - collaborative discussion that builds a complete specification before formal phases/tasks are created. +This balance comes from **draft planning** - collaborative discussion that finds the right level of detail before formal phases/tasks are created. ### No Hallucinations diff --git a/skills/technical-planning/references/planning-approach.md b/skills/technical-planning/references/planning-approach.md index a881380bf..e219cebcd 100644 --- a/skills/technical-planning/references/planning-approach.md +++ b/skills/technical-planning/references/planning-approach.md @@ -24,8 +24,8 @@ Draft planning produces a **standalone specification** containing everything nee **Before jumping to formal phases and tasks**: 1. Create `draft-plan.md` in the plans directory 2. Collaborate with user to build the Specification section -3. Continue until specification is complete and unambiguous -4. Proceed to formal planning only when draft leaves no room for interpretation +3. Continue until WHAT/WHY/edge cases/acceptance criteria are clear +4. Proceed to formal planning when the draft has the right level of detail for this feature **Immediate capture rule**: After each user response, update the draft document BEFORE your next question. Distill validated information into the Specification section immediately. diff --git a/skills/technical-planning/references/planning-conversations.md b/skills/technical-planning/references/planning-conversations.md index 09b8746a2..7c509f920 100644 --- a/skills/technical-planning/references/planning-conversations.md +++ b/skills/technical-planning/references/planning-conversations.md @@ -9,9 +9,9 @@ Draft planning exists to produce a **standalone specification** containing everything needed to construct formal phases and tasks. It is NOT a summary. It is NOT conversation notes. It is the complete, unambiguous foundation for formal planning. The draft is where you collaborate with the user to ensure: -1. **Nothing is missing** - all detail required for implementation is present +1. **Nothing is missing** - the WHAT is clearly defined with enough detail 2. **Nothing is hallucinated** - only real, validated information remains -3. **No room for interpretation** - implementation agents have zero creative latitude +3. **The right level of detail** - not so vague it's useless, not so prescriptive it constrains implementation unnecessarily ### Two Scenarios That Require Draft Planning @@ -38,13 +38,15 @@ Most real planning involves **both** - enriching some areas while filtering othe ### The Draft as Deliverable At the end of draft planning, `draft-plan.md` must be a **standalone file** containing: -- Everything needed to construct formal phases/tasks -- Enough detail that implementation has no ambiguity +- Clear definition of WHAT we're building and WHY +- Edge cases the implementation needs to be aware of +- Testing ideas and acceptance criteria +- Optionally, guidance on HOW to approach it (when helpful, not prescriptive) - Only validated information, not summaries or assumptions **Anti-pattern**: A draft that summarizes the discussion into three bullet points is useless. That's just another file with vague content that requires re-discovery. -**Correct pattern**: A draft that captures specific decisions, specific approaches, specific constraints, specific edge cases - everything the formal plan needs spelled out. +**Correct pattern**: A draft that defines the feature clearly - what it does, why it exists, what edge cases matter, how we'll know it's complete. Implementation can then take charge or collaborate to figure out the approach. ## Two-Phase Planning @@ -128,11 +130,15 @@ This section is the deliverable. Update it continuously as clarity emerges. ### What We're Building -[Specific, concrete description - not a summary. Include enough detail that someone could understand the scope without reading source materials.] +[Specific, concrete description of the feature - not a summary. What does it do? What problem does it solve? Include enough detail that someone understands the scope without reading source materials.] -### Approach +### Why We're Building It -[How we will build this. Specific patterns, sequences, constraints. Not "we'll handle errors" but "validation errors return 422 with field-level messages using the existing ValidationException handler".] +[The motivation. What user need or technical need does this address? This context helps implementation make good decisions.] + +### Approach (Optional) + +[Include when there's a specific approach that should be followed. Leave out or keep light when implementation should figure this out. This section can range from "use the existing X pattern" to detailed guidance - whatever level is appropriate for this feature.] ### Scope Boundaries @@ -150,10 +156,25 @@ This section is the deliverable. Update it continuously as clarity emerges. |----------|--------|-----------| | [decision point] | [what we chose] | [why - be specific] | -### Edge Cases and Constraints +### Edge Cases to Handle + +- [Edge case that implementation must be aware of] +- [Another edge case - what makes this tricky] + +### Constraints + +- [Technical constraint that limits options] +- [Business constraint that affects scope] + +### Testing and Acceptance + +How we'll know this is complete: +- [Acceptance criterion] +- [Another criterion] -- [Specific edge case]: [how it will be handled] -- [Constraint]: [how it affects implementation] +Testing ideas: +- [Test scenario to cover] +- [Edge case that needs a test] ### Open Questions (Blocking) @@ -198,13 +219,15 @@ Commits are your safety net. A context refresh with uncommitted work = lost work ## Transitioning to Formal Plan Draft planning is complete when the **Specification section** contains: -- [ ] Complete description of what we're building (no ambiguity) -- [ ] Specific approach with enough detail for implementation -- [ ] Clear scope boundaries (in/out) -- [ ] All technical decisions documented with reasoning -- [ ] All edge cases identified with handling approach +- [ ] Clear description of WHAT we're building and WHY +- [ ] Scope boundaries (in/out) +- [ ] Edge cases implementation needs to handle +- [ ] Testing ideas and acceptance criteria +- [ ] Approach guidance (if needed - this varies by feature) - [ ] No blocking open questions remaining +The right level of detail varies. Some features need detailed HOW guidance; others just need clear WHAT/WHY and can leave implementation to figure out the approach. The draft process is about finding that line. + **Transition process**: 1. Review the Specification section together 2. User confirms it contains everything needed @@ -220,56 +243,61 @@ Draft planning is complete when the **Specification section** contains: ## What We're Building A caching layer for the API. -## Approach -We'll add Redis caching to improve performance. - ## Scope - Add caching - Handle invalidation ``` -This is useless. It says nothing concrete. An implementation agent reading this would have to make everything up - cache keys, TTLs, what gets cached, invalidation strategy, error handling. +This is useless. It says nothing concrete. What endpoints? What's the goal? What edge cases matter? How do we know it's working? **Good Draft** (enables formal planning): ```markdown ## What We're Building -Response caching for the /api/products endpoints. Cache full JSON responses -keyed by endpoint + query parameters. Target: reduce database load by 80% -for repeated identical requests. +Response caching for the /api/products endpoints to reduce database load +for repeated identical requests. Target: 80% reduction in DB hits for +product listing pages. -## Approach -- Use existing Redis connection from config/database.php -- Cache at controller level using Laravel's Cache facade -- Key format: "products:{endpoint}:{hash(query_params)}" -- TTL: 5 minutes for list endpoints, 15 minutes for single product -- Cache-Control headers: public, max-age matching TTL -- Invalidation: Tag-based using "products" tag, clear on any Product model event +## Why We're Building It +Product pages are our highest-traffic endpoints. Currently every request +hits the database, even for identical queries seconds apart. Users see +slow page loads during peak traffic. ## Scope Boundaries **In scope**: - GET /api/products (list with filters) - GET /api/products/{id} (single product) -- Cache warming not included in initial implementation **Out of scope**: -- POST/PUT/DELETE endpoints (no caching) +- POST/PUT/DELETE endpoints (no caching needed) - User-specific data (cart, wishlist) - different caching strategy later - CDN integration - separate initiative -## Technical Decisions -| Decision | Choice | Reasoning | -|----------|--------|-----------| -| Cache location | Controller | Simpler than middleware, can make per-endpoint decisions | -| TTL strategy | Fixed per endpoint | Predictable, avoids complexity of adaptive TTLs | -| Invalidation | Tag-based | Product updates rare, tag clear is simple and sufficient | - -## Edge Cases -- Empty result sets: Cache them (prevents repeated DB hits for non-existent filters) -- Large responses (>1MB): Still cache, Redis handles it, revisit if memory issues -- Redis unavailable: Fail open, skip cache, log warning, don't break requests +## Approach +Use Redis via Laravel's Cache facade. Consider caching at controller level +for simplicity, but implementation can propose alternatives. + +Key considerations: +- Need to handle cache invalidation when products are updated +- TTLs should balance freshness with cache hit rate + +## Edge Cases to Handle +- Empty result sets (should we cache "no results"?) +- Very large responses (>1MB) +- Redis unavailable (fail open vs fail closed?) + +## Testing and Acceptance +How we'll know it's complete: +- Product list pages respond from cache on repeat requests +- Cache invalidates when product data changes +- No user-facing errors when Redis is unavailable + +Testing ideas: +- Load test showing DB query reduction +- Test cache invalidation on product update +- Test Redis failure handling ``` -The good draft leaves nothing to imagination. Implementation knows exactly what to build. +The good draft is clear about WHAT and WHY, identifies the edge cases, and gives implementation enough context to make good decisions. It includes approach guidance without being overly prescriptive. ## Anti-Hallucination From 23a3cabdc83bf23b35425f7ff3da6e7af697904b Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 10 Dec 2025 21:19:57 +0000 Subject: [PATCH 03/11] Remove negative examples that could reinforce unwanted behavior Reframe guidance as positive patterns instead of showing what not to do: - Replace "Bad Draft" / "Good Draft" with single example of complete draft - Replace "Bad" / "Good" comparisons with positive examples only - Reframe "Anti-Hallucination" as "Building Through Collaboration" - Keep absolute rules (don't write code during planning) but remove soft guidance framed as negatives --- .../references/guidelines.md | 12 ++---- .../references/planning-conversations.md | 40 +++++-------------- 2 files changed, 14 insertions(+), 38 deletions(-) diff --git a/skills/technical-planning/references/guidelines.md b/skills/technical-planning/references/guidelines.md index 9e877d81e..9cb599b6a 100644 --- a/skills/technical-planning/references/guidelines.md +++ b/skills/technical-planning/references/guidelines.md @@ -28,11 +28,9 @@ The draft process is collaborative - together with the user, you figure out how - HOW to approach it (varies by feature complexity and team familiarity) - Specific patterns or constraints -**Bad**: "Add caching to improve performance" -- Too vague. What endpoints? What's the goal? What edge cases? +**Example**: "Add caching to /api/products to reduce DB load. Target 80% fewer queries. Handle: empty results, large responses, Redis failures. Implementation can determine TTLs and key strategy." -**Good**: "Add caching to /api/products to reduce DB load. Target 80% fewer queries. Handle: empty results, large responses, Redis failures. Implementation can determine TTLs and key strategy." -- Clear WHAT and WHY. Edge cases identified. HOW left to implementation where appropriate. +This example shows clear WHAT and WHY, identifies edge cases, and leaves HOW to implementation where appropriate. This balance comes from **draft planning** - collaborative discussion that finds the right level of detail before formal phases/tasks are created. @@ -52,9 +50,7 @@ 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. +**If no documents exist**: You've lost the planning conversation. Be honest about that and ask again for what you need. ### Immediate Capture @@ -88,7 +84,7 @@ You have summaries, not nuance. The planning documents ARE the nuance. - Take 5-30 minutes - Do one clear thing -**Bad tasks**: "Implement caching layer" (too big), "Handle errors" (too vague) +**Example good tasks**: "Add cache check before DB query in ProductController::index", "Return cached response when Redis hit occurs", "Log cache miss and fetch from database" ## Micro Acceptance diff --git a/skills/technical-planning/references/planning-conversations.md b/skills/technical-planning/references/planning-conversations.md index 7c509f920..73707dea2 100644 --- a/skills/technical-planning/references/planning-conversations.md +++ b/skills/technical-planning/references/planning-conversations.md @@ -44,9 +44,7 @@ At the end of draft planning, `draft-plan.md` must be a **standalone file** cont - Optionally, guidance on HOW to approach it (when helpful, not prescriptive) - Only validated information, not summaries or assumptions -**Anti-pattern**: A draft that summarizes the discussion into three bullet points is useless. That's just another file with vague content that requires re-discovery. - -**Correct pattern**: A draft that defines the feature clearly - what it does, why it exists, what edge cases matter, how we'll know it's complete. Implementation can then take charge or collaborate to figure out the approach. +A good draft defines the feature clearly - what it does, why it exists, what edge cases matter, how we'll know it's complete. Implementation can then take charge or collaborate to figure out the approach. ## Two-Phase Planning @@ -97,11 +95,11 @@ This is non-negotiable. Context windows refresh without warning. Three hours of ### What to Capture -Record **what the user said AND why**, not just conclusions: +Record **what the user said AND why**, not just conclusions. -**Bad**: "Phase 1 will handle authentication" +**Example**: "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" -**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, not just the decision. ### Capture the Reasoning Journey @@ -236,21 +234,7 @@ The right level of detail varies. Some features need detailed HOW guidance; othe **The Specification is standalone** - formal planning should not require going back to source discussion documents. Everything needed is in the draft. -## Good Draft vs Bad Draft - -**Bad Draft** (creates no value): -```markdown -## What We're Building -A caching layer for the API. - -## Scope -- Add caching -- Handle invalidation -``` - -This is useless. It says nothing concrete. What endpoints? What's the goal? What edge cases matter? How do we know it's working? - -**Good Draft** (enables formal planning): +## Example: A Complete Draft Specification ```markdown ## What We're Building Response caching for the /api/products endpoints to reduce database load @@ -297,18 +281,14 @@ Testing ideas: - Test Redis failure handling ``` -The good draft is clear about WHAT and WHY, identifies the edge cases, and gives implementation enough context to make good decisions. It includes approach guidance without being overly prescriptive. +This draft is clear about WHAT and WHY, identifies the edge cases, and gives implementation enough context to make good decisions. It includes approach guidance without being overly prescriptive. -## Anti-Hallucination +## Building Through Collaboration -During draft planning, you are **building** the specification through discussion. Do not invent details - ask. +During draft planning, you are **building** the specification through discussion. When information is missing, ask. -**Do**: "The discussion mentions caching but doesn't specify TTLs. What cache duration makes sense for your use case?" - -**Don't**: Assume TTLs, cache keys, or strategies that weren't discussed. +**Example**: "The discussion mentions caching but doesn't specify TTLs. What cache duration makes sense for your use case?" After context refresh: - **If the draft exists**: Read it. Trust it. The Specification section has the detail you've lost. -- **If no draft exists**: You've lost the planning conversation. Be honest. Don't pretend you remember details you don't have. - -**Never invent reasoning or detail** that wasn't captured. If it's not in the document, ask again. +- **If no draft exists**: You've lost the planning conversation. Be honest about that and ask again for what you need. From 61e607b71cf92e587ff324e76e1adf9cbb29334e Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 10 Dec 2025 21:26:00 +0000 Subject: [PATCH 04/11] Remove constraining examples and team references - Remove draft specification example (draft will vary by task) - Remove task examples and other constraining examples - Remove "team familiarity" reference - this is user + Claude collaboration --- .../references/guidelines.md | 8 +-- .../references/planning-conversations.md | 57 +------------------ 2 files changed, 2 insertions(+), 63 deletions(-) diff --git a/skills/technical-planning/references/guidelines.md b/skills/technical-planning/references/guidelines.md index 9cb599b6a..b1818b679 100644 --- a/skills/technical-planning/references/guidelines.md +++ b/skills/technical-planning/references/guidelines.md @@ -25,13 +25,9 @@ The draft process is collaborative - together with the user, you figure out how - Testing ideas and acceptance criteria **Include when helpful**: -- HOW to approach it (varies by feature complexity and team familiarity) +- HOW to approach it (varies by feature complexity) - Specific patterns or constraints -**Example**: "Add caching to /api/products to reduce DB load. Target 80% fewer queries. Handle: empty results, large responses, Redis failures. Implementation can determine TTLs and key strategy." - -This example shows clear WHAT and WHY, identifies edge cases, and leaves HOW to implementation where appropriate. - This balance comes from **draft planning** - collaborative discussion that finds the right level of detail before formal phases/tasks are created. ### No Hallucinations @@ -84,8 +80,6 @@ You have summaries, not nuance. The planning documents ARE the nuance. - Take 5-30 minutes - Do one clear thing -**Example good tasks**: "Add cache check before DB query in ProductController::index", "Return cached response when Redis hit occurs", "Log cache miss and fetch from database" - ## Micro Acceptance The test name that proves task completion. Implementation will: diff --git a/skills/technical-planning/references/planning-conversations.md b/skills/technical-planning/references/planning-conversations.md index 73707dea2..f0f8485a9 100644 --- a/skills/technical-planning/references/planning-conversations.md +++ b/skills/technical-planning/references/planning-conversations.md @@ -95,11 +95,7 @@ This is non-negotiable. Context windows refresh without warning. Three hours of ### What to Capture -Record **what the user said AND why**, not just conclusions. - -**Example**: "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, not just the decision. +Record **what the user said AND why**, not just conclusions. Capture the reasoning, not just the decision. ### Capture the Reasoning Journey @@ -234,61 +230,10 @@ The right level of detail varies. Some features need detailed HOW guidance; othe **The Specification is standalone** - formal planning should not require going back to source discussion documents. Everything needed is in the draft. -## Example: A Complete Draft Specification -```markdown -## What We're Building -Response caching for the /api/products endpoints to reduce database load -for repeated identical requests. Target: 80% reduction in DB hits for -product listing pages. - -## Why We're Building It -Product pages are our highest-traffic endpoints. Currently every request -hits the database, even for identical queries seconds apart. Users see -slow page loads during peak traffic. - -## Scope Boundaries -**In scope**: -- GET /api/products (list with filters) -- GET /api/products/{id} (single product) - -**Out of scope**: -- POST/PUT/DELETE endpoints (no caching needed) -- User-specific data (cart, wishlist) - different caching strategy later -- CDN integration - separate initiative - -## Approach -Use Redis via Laravel's Cache facade. Consider caching at controller level -for simplicity, but implementation can propose alternatives. - -Key considerations: -- Need to handle cache invalidation when products are updated -- TTLs should balance freshness with cache hit rate - -## Edge Cases to Handle -- Empty result sets (should we cache "no results"?) -- Very large responses (>1MB) -- Redis unavailable (fail open vs fail closed?) - -## Testing and Acceptance -How we'll know it's complete: -- Product list pages respond from cache on repeat requests -- Cache invalidates when product data changes -- No user-facing errors when Redis is unavailable - -Testing ideas: -- Load test showing DB query reduction -- Test cache invalidation on product update -- Test Redis failure handling -``` - -This draft is clear about WHAT and WHY, identifies the edge cases, and gives implementation enough context to make good decisions. It includes approach guidance without being overly prescriptive. - ## Building Through Collaboration During draft planning, you are **building** the specification through discussion. When information is missing, ask. -**Example**: "The discussion mentions caching but doesn't specify TTLs. What cache duration makes sense for your use case?" - After context refresh: - **If the draft exists**: Read it. Trust it. The Specification section has the detail you've lost. - **If no draft exists**: You've lost the planning conversation. Be honest about that and ask again for what you need. From 77f4b346782728e8ac18bcc9ef765e0ecf2bf924 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 10 Dec 2025 21:27:09 +0000 Subject: [PATCH 05/11] Restore 'never invent reasoning' rule in guidelines --- skills/technical-planning/references/guidelines.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/skills/technical-planning/references/guidelines.md b/skills/technical-planning/references/guidelines.md index b1818b679..7d2f343f0 100644 --- a/skills/technical-planning/references/guidelines.md +++ b/skills/technical-planning/references/guidelines.md @@ -48,6 +48,8 @@ You have summaries, not nuance. The planning documents ARE the nuance. **If no documents exist**: You've lost the planning conversation. Be honest about that and ask again for what you need. +**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. From 44b8fb60b8d6ba2f26745b08e279344f4eb0eb88 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 10 Dec 2025 21:28:03 +0000 Subject: [PATCH 06/11] Add '2-3 exchanges' rule back to planning-approach.md --- skills/technical-planning/references/planning-approach.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/technical-planning/references/planning-approach.md b/skills/technical-planning/references/planning-approach.md index e219cebcd..87bdc3e1c 100644 --- a/skills/technical-planning/references/planning-approach.md +++ b/skills/technical-planning/references/planning-approach.md @@ -27,7 +27,7 @@ Draft planning produces a **standalone specification** containing everything nee 3. Continue until WHAT/WHY/edge cases/acceptance criteria are clear 4. Proceed to formal planning when the draft has the right level of detail for this feature -**Immediate capture rule**: After each user response, update the draft document BEFORE your next question. Distill validated information into the Specification section immediately. +**Immediate capture rule**: After each user response, update the draft document BEFORE your next question. Distill validated information into the Specification section immediately. Never let more than 2-3 exchanges pass without writing. See **[planning-conversations.md](planning-conversations.md)** for full draft planning workflow. From d11f7da5a31e4845f504a63e219ea5a2cf61bfc2 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 10 Dec 2025 21:30:47 +0000 Subject: [PATCH 07/11] Add product owner and documenter roles to planning skill --- skills/technical-planning/SKILL.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/skills/technical-planning/SKILL.md b/skills/technical-planning/SKILL.md index a75ea8d7c..466e6ac73 100644 --- a/skills/technical-planning/SKILL.md +++ b/skills/technical-planning/SKILL.md @@ -5,7 +5,9 @@ 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**. You collaborate with the user - who brings both technical and product expertise - to translate discussion decisions into actionable implementation plans. + +Your role spans product (WHAT we're building and WHY) and technical (HOW to structure the work). Together you create plans with testable phases and atomic tasks that implementation can execute. Convert discussion docs into implementation plans. Output location depends on chosen destination. From 45030b0a34588a2674668a43857cf3a3f4ed2281 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 10 Dec 2025 21:34:56 +0000 Subject: [PATCH 08/11] Refactor SKILL.md per skill-creator guidelines (172 -> 79 lines) Follow Anthropic's skill-creator guidance: - Keep SKILL.md lean, detailed info in references - Avoid duplication between SKILL.md and reference files - Progressive disclosure: essentials in SKILL.md, details on demand Removed duplicated content (already in reference files): - Detailed "What to capture" list -> planning-conversations.md - Detailed commit rules -> guidelines.md, planning-approach.md - Plan contents details -> template.md - Implementation flow -> guidelines.md, output adapters Kept essential rules concise in SKILL.md with clear links to references. --- skills/technical-planning/SKILL.md | 167 +++++++---------------------- 1 file changed, 37 insertions(+), 130 deletions(-) diff --git a/skills/technical-planning/SKILL.md b/skills/technical-planning/SKILL.md index 466e6ac73..f23a943ba 100644 --- a/skills/technical-planning/SKILL.md +++ b/skills/technical-planning/SKILL.md @@ -5,168 +5,75 @@ description: "Transform technical discussion documents into actionable implement # Technical Planning -Act as **expert technical architect**, **product owner**, and **plan documenter**. You collaborate with the user - who brings both technical and product expertise - to translate discussion decisions into actionable implementation plans. +Act as **expert technical architect**, **product owner**, and **plan documenter**. Collaborate with the user - who brings both technical and product expertise - to translate discussion decisions into actionable implementation plans. -Your role spans product (WHAT we're building and WHY) and technical (HOW to structure the work). Together you create plans with testable phases and atomic tasks that implementation can execute. - -Convert discussion docs into implementation plans. Output location depends on chosen destination. - -## Output Destinations - -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). - -| 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/` | - -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 - -**Default**: If no destination specified, use local markdown. - -The planning *approach* is the same regardless of destination. Only the output format changes. +Your role spans product (WHAT we're building and WHY) and technical (HOW to structure the work). Together you create plans with testable phases and atomic tasks. ## Four-Phase Workflow 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 +2. **Planning** (YOU): Structure the work into phases and tasks +3. **Implementation** (next): TDD execution of your plan +4. **Review** (final): Validate against decisions and plan -You're at step 2. Don't implement. +You're at step 2. Create the plan, don't implement. -## Draft Planning: Building the Specification +## Output Destinations -Draft planning produces a **standalone specification** - a document containing everything needed to construct formal phases and tasks. It is NOT a summary. It is NOT conversation notes. +Plans can be stored in different formats. Use the appropriate adapter: -**The draft serves two purposes**: +| Destination | Output | Adapter | +|-------------|--------|---------| +| **Local Markdown** (default) | `plan.md` file | [output-local-markdown.md](references/output-local-markdown.md) | +| **Linear** | Linear project | [output-linear.md](references/output-linear.md) | +| **Backlog.md** | Task files in `backlog/` | [output-backlog-md.md](references/output-backlog-md.md) | -1. **Enrichment**: Source materials may capture WHAT and WHY but not HOW. Draft planning adds missing detail through collaborative discussion (not hallucination). +## Draft Planning -2. **Filtering**: Source materials may contain noise, tangents, speculation, or hallucinated content. Draft planning removes this through collaborative review. +For complex features, planning itself requires discussion. Use draft planning to build a **standalone specification** before creating formal phases/tasks. -**Two-phase planning**: -1. **Draft Planning**: Collaborate to build complete specification in `draft-plan.md` -2. **Formal Planning**: Structure the specification into phases/tasks +**Draft serves two purposes**: +1. **Enrichment**: Add missing detail through collaborative discussion +2. **Filtering**: Remove noise, speculation, hallucination through review See **[planning-conversations.md](references/planning-conversations.md)** for the full draft planning workflow. -**The draft captures** WHAT we're building, WHY, edge cases, and testing/acceptance criteria. HOW much detail to include varies - some features need detailed approach guidance, others just need clarity on what to build. The draft process is collaborative - together you find the right level of detail. - -**When to use draft planning**: -- Source materials need enrichment (missing HOW details) -- Source materials need filtering (noise, speculation, hallucination) -- Complex features with unclear approach -- Multiple valid ways to structure the work - -**Skip to formal planning when**: -- Source materials already contain complete specification -- Small feature with obvious structure -- All detail already worked out elsewhere - -## 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 +**Skip draft planning when** source materials already contain complete specification. -**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 +## Critical Rules -**Why**: You lose memory on context refresh. Commits prevent losing hours of planning work. This is non-negotiable. +**Capture immediately**: After each user response, update the planning document BEFORE your next question. Never let more than 2-3 exchanges pass without writing. Context refresh = lost work. -## You Create Plans, NOT Code +**Commit frequently**: Commit planning docs at natural breaks, after significant exchanges, and before any context refresh. -**Your job**: Write plan document with phases, tasks, and acceptance criteria -**NOT your job**: Implement it, modify files, write production code +**Never invent reasoning**: If it's not in the document, ask again. -## Phase > Task Hierarchy +**Create plans, not code**: Your job is phases, tasks, and acceptance criteria - not implementation. -Plans use a two-level structure: +## Plan Structure ``` Phase (higher level) ├── Goal: What this phase accomplishes -├── Acceptance Criteria: How we know the phase is complete +├── Acceptance Criteria: How we know phase is complete └── Tasks (granular work units) - ├── Task 1: Description + micro acceptance + edge cases - ├── Task 2: Description + micro acceptance - └── Task 3: Description + micro acceptance + └── Each task: Description + micro acceptance + edge cases ``` -**Phase**: Independently testable unit. Has acceptance criteria. +**Phase**: Independently testable unit with 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 - -## 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.** +See **[template.md](references/template.md)** for plan document structure. ## 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 +**Core workflow**: +- **[planning-conversations.md](references/planning-conversations.md)** - Draft planning workflow +- **[planning-approach.md](references/planning-approach.md)** - Step-by-step process - **[guidelines.md](references/guidelines.md)** - Best practices, task sizing -- **[template.md](references/template.md)** - Plan document template (for local markdown) - -**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 - -## Remember +- **[template.md](references/template.md)** - Plan document template -You're the architect, not the builder. Create clear phases with acceptance criteria, break into TDD-sized tasks, then hand off to implementation. +**Output adapters** (use based on destination): +- **[output-local-markdown.md](references/output-local-markdown.md)** +- **[output-linear.md](references/output-linear.md)** +- **[output-backlog-md.md](references/output-backlog-md.md)** From 189d91995934d7c0678a35e332d96bc36d4dafb6 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 10 Dec 2025 22:00:03 +0000 Subject: [PATCH 09/11] Restructure planning skill with clear Path A/B flow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Major restructure to separate draft and formal planning clearly: SKILL.md (52 lines): - Lean with clear personality (architect + product owner + documenter) - CRITICAL: Must ask user which path before proceeding - Path A: Draft planning → draft-planning.md - Path B: Formal planning → formal-planning.md → output adapter New reference files: - draft-planning.md: Complete draft planning workflow - formal-planning.md: Common formal planning process Merged/removed: - template.md → merged into output-local-markdown.md - planning-approach.md → split between draft/formal - guidelines.md → split between draft/formal - planning-conversations.md → replaced by draft-planning.md Key change: Agent must ASK user which path, not decide themselves. --- skills/technical-planning/SKILL.md | 77 ++---- .../references/draft-planning.md | 146 +++++++++++ .../references/formal-planning.md | 128 ++++++++++ .../references/guidelines.md | 120 --------- .../references/output-local-markdown.md | 140 +++++++--- .../references/planning-approach.md | 93 ------- .../references/planning-conversations.md | 239 ------------------ .../technical-planning/references/template.md | 149 ----------- 8 files changed, 399 insertions(+), 693 deletions(-) create mode 100644 skills/technical-planning/references/draft-planning.md create mode 100644 skills/technical-planning/references/formal-planning.md delete mode 100644 skills/technical-planning/references/guidelines.md delete mode 100644 skills/technical-planning/references/planning-approach.md delete mode 100644 skills/technical-planning/references/planning-conversations.md delete mode 100644 skills/technical-planning/references/template.md diff --git a/skills/technical-planning/SKILL.md b/skills/technical-planning/SKILL.md index f23a943ba..1f76da869 100644 --- a/skills/technical-planning/SKILL.md +++ b/skills/technical-planning/SKILL.md @@ -5,75 +5,48 @@ description: "Transform technical discussion documents into actionable implement # Technical Planning -Act as **expert technical architect**, **product owner**, and **plan documenter**. Collaborate with the user - who brings both technical and product expertise - to translate discussion decisions into actionable implementation plans. +Act as **expert technical architect**, **product owner**, and **plan documenter**. Collaborate with the user to translate discussion decisions into actionable implementation plans. -Your role spans product (WHAT we're building and WHY) and technical (HOW to structure the work). Together you create plans with testable phases and atomic tasks. +Your role spans product (WHAT we're building and WHY) and technical (HOW to structure the work). -## Four-Phase Workflow +## You Must Ask Before Proceeding -1. **Discussion** (previous): WHAT and WHY - decisions, architecture, edge cases -2. **Planning** (YOU): Structure the work into phases and tasks -3. **Implementation** (next): TDD execution of your plan -4. **Review** (final): Validate against decisions and plan +**If you don't know which path to take, ask the user.** -You're at step 2. Create the plan, don't implement. +There are two paths: +- **Path A**: Draft planning first, then formal planning +- **Path B**: Formal planning directly -## Output Destinations +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?" -Plans can be stored in different formats. Use the appropriate adapter: +## Path A: Draft Planning -| Destination | Output | Adapter | -|-------------|--------|---------| -| **Local Markdown** (default) | `plan.md` file | [output-local-markdown.md](references/output-local-markdown.md) | -| **Linear** | Linear project | [output-linear.md](references/output-linear.md) | -| **Backlog.md** | Task files in `backlog/` | [output-backlog-md.md](references/output-backlog-md.md) | +User wants to build the specification collaboratively before creating the formal plan. -## Draft Planning +**Load**: [draft-planning.md](references/draft-planning.md) -For complex features, planning itself requires discussion. Use draft planning to build a **standalone specification** before creating formal phases/tasks. +**Output**: `draft-plan.md` - standalone specification -**Draft serves two purposes**: -1. **Enrichment**: Add missing detail through collaborative discussion -2. **Filtering**: Remove noise, speculation, hallucination through review +**When complete**: User signs off, then proceed to Path B. -See **[planning-conversations.md](references/planning-conversations.md)** for the full draft planning workflow. +## Path B: Formal Planning -**Skip draft planning when** source materials already contain complete specification. +User wants to create the formal implementation plan (directly, or after draft). + +**Load**: [formal-planning.md](references/formal-planning.md) + +**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 -**Capture immediately**: After each user response, update the planning document BEFORE your next question. Never let more than 2-3 exchanges pass without writing. Context refresh = lost work. +**Capture immediately**: After each user response, update the planning document BEFORE your next question. Never let more than 2-3 exchanges pass without writing. -**Commit frequently**: Commit planning docs at natural breaks, after significant exchanges, and before any context refresh. +**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. **Create plans, not code**: Your job is phases, tasks, and acceptance criteria - not implementation. - -## Plan Structure - -``` -Phase (higher level) -├── Goal: What this phase accomplishes -├── Acceptance Criteria: How we know phase is complete -└── Tasks (granular work units) - └── Each task: Description + micro acceptance + edge cases -``` - -**Phase**: Independently testable unit with acceptance criteria. -**Task**: Single TDD cycle. One task = one test = one commit. - -See **[template.md](references/template.md)** for plan document structure. - -## Reference Files - -**Core workflow**: -- **[planning-conversations.md](references/planning-conversations.md)** - Draft planning workflow -- **[planning-approach.md](references/planning-approach.md)** - Step-by-step process -- **[guidelines.md](references/guidelines.md)** - Best practices, task sizing -- **[template.md](references/template.md)** - Plan document template - -**Output adapters** (use based on destination): -- **[output-local-markdown.md](references/output-local-markdown.md)** -- **[output-linear.md](references/output-linear.md)** -- **[output-backlog-md.md](references/output-backlog-md.md)** 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..d482cd48f --- /dev/null +++ b/skills/technical-planning/references/formal-planning.md @@ -0,0 +1,128 @@ +# 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 +- 5-30 minutes of work + +### 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) +- Take 5-30 minutes +- 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 7d2f343f0..000000000 --- a/skills/technical-planning/references/guidelines.md +++ /dev/null @@ -1,120 +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 - -### Finding the Right Level of Detail - -The draft process is collaborative - together with the user, you figure out how much detail is needed for THIS feature. Some features need detailed HOW guidance; others just need clear WHAT/WHY and implementation can work out the approach. - -**Always include**: -- WHAT we're building (specific, not vague) -- WHY we're building it (the motivation) -- Edge cases to be aware of -- Testing ideas and acceptance criteria - -**Include when helpful**: -- HOW to approach it (varies by feature complexity) -- Specific patterns or constraints - -This balance comes from **draft planning** - collaborative discussion that finds the right level of detail before formal phases/tasks are created. - -### 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 about that and ask again for what you need. - -**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 - -## 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 87bdc3e1c..000000000 --- a/skills/technical-planning/references/planning-approach.md +++ /dev/null @@ -1,93 +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 (Building the Specification) - -Draft planning produces a **standalone specification** containing everything needed for formal planning. This is NOT conversation notes or a summary. - -**The draft process**: -1. **Enrichment**: Add missing detail through collaborative discussion (not hallucination) -2. **Filtering**: Remove noise, speculation, and hallucinated content through collaborative review - -**Before jumping to formal phases and tasks**: -1. Create `draft-plan.md` in the plans directory -2. Collaborate with user to build the Specification section -3. Continue until WHAT/WHY/edge cases/acceptance criteria are clear -4. Proceed to formal planning when the draft has the right level of detail for this feature - -**Immediate capture rule**: After each user response, update the draft document BEFORE your next question. Distill validated information into the Specification section immediately. Never let more than 2-3 exchanges pass without writing. - -See **[planning-conversations.md](planning-conversations.md)** for full draft planning workflow. - -**Skip draft planning when**: Source materials already contain complete specification with all detail needed for implementation. - -### 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 f0f8485a9..000000000 --- a/skills/technical-planning/references/planning-conversations.md +++ /dev/null @@ -1,239 +0,0 @@ -# Planning Conversations - -*Reference for **[technical-planning](../SKILL.md)*** - ---- - -## The Purpose of Draft Planning - -Draft planning exists to produce a **standalone specification** containing everything needed to construct formal phases and tasks. It is NOT a summary. It is NOT conversation notes. It is the complete, unambiguous foundation for formal planning. - -The draft is where you collaborate with the user to ensure: -1. **Nothing is missing** - the WHAT is clearly defined with enough detail -2. **Nothing is hallucinated** - only real, validated information remains -3. **The right level of detail** - not so vague it's useless, not so prescriptive it constrains implementation unnecessarily - -### Two Scenarios That Require Draft Planning - -**Scenario A: Enrichment (Adding Detail)** - -Source materials (discussion docs, etc.) may capture WHAT to build and WHY, but haven't fully rounded out HOW to approach it. The draft process adds this detail through collaborative discussion - not hallucination. - -- What's the actual sequence of work? -- What are the specific constraints? -- What patterns or approaches will we use? -- What edge cases need explicit handling? - -**Scenario B: Filtering (Removing Noise)** - -Source materials may contain too much detail, tangential discussion, speculative content, or hallucinated information. The draft process filters this through collaborative review. - -- What's actually in scope vs mentioned but not committed to? -- Which discussed options were rejected? -- What was speculation vs decision? -- What information is validated vs assumed? - -Most real planning involves **both** - enriching some areas while filtering others. - -### The Draft as Deliverable - -At the end of draft planning, `draft-plan.md` must be a **standalone file** containing: -- Clear definition of WHAT we're building and WHY -- Edge cases the implementation needs to be aware of -- Testing ideas and acceptance criteria -- Optionally, guidance on HOW to approach it (when helpful, not prescriptive) -- Only validated information, not summaries or assumptions - -A good draft defines the feature clearly - what it does, why it exists, what edge cases matter, how we'll know it's complete. Implementation can then take charge or collaborate to figure out the approach. - -## Two-Phase Planning - -### Phase A: Draft Planning (Build the Specification) - -Collaborative discussion that produces a complete specification: -- What exactly are we building? -- How exactly will we approach it? -- What specific constraints and edge cases exist? -- What's in scope, what's out? - -**Output**: `draft-plan.md` - standalone specification ready for structuring - -### Phase B: Formal Planning (Structure the Specification) - -Convert the complete 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**: -- Source materials need enrichment (missing HOW details) -- Source materials need filtering (contains noise, speculation, hallucination) -- Complex feature with unclear approach -- Multiple valid ways to structure the work -- User wants to collaborate on the specification - -**Skip to formal planning when**: -- Source materials already contain complete specification -- Small feature with obvious structure -- User has already worked out all the detail elsewhere - -## 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. Capture the reasoning, not just the decision. - -### 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 - -The draft has two sections: a **Planning Log** (running capture) and a **Specification** (the deliverable). The log feeds the specification. - -```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 of the feature - not a summary. What does it do? What problem does it solve? Include enough detail that someone understands the scope without reading source materials.] - -### Why We're Building It - -[The motivation. What user need or technical need does this address? This context helps implementation make good decisions.] - -### Approach (Optional) - -[Include when there's a specific approach that should be followed. Leave out or keep light when implementation should figure this out. This section can range from "use the existing X pattern" to detailed guidance - whatever level is appropriate for this feature.] - -### Scope Boundaries - -**In scope**: -- [Specific item with enough detail to be unambiguous] -- [Specific item] - -**Out of scope** (explicitly excluded): -- [Item and why excluded] -- [Item] - -### Technical Decisions - -| Decision | Choice | Reasoning | -|----------|--------|-----------| -| [decision point] | [what we chose] | [why - be specific] | - -### Edge Cases to Handle - -- [Edge case that implementation must be aware of] -- [Another edge case - what makes this tricky] - -### Constraints - -- [Technical constraint that limits options] -- [Business constraint that affects scope] - -### Testing and Acceptance - -How we'll know this is complete: -- [Acceptance criterion] -- [Another criterion] - -Testing ideas: -- [Test scenario to cover] -- [Edge case that needs a test] - -### 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] Initial Discussion - -[What was discussed, decisions made, reasoning. Use this to populate the Specification section above.] - -### [timestamp] [Topic] - -[Continue capturing. After each exchange, update BOTH this log AND the Specification section.] -``` - -### Key Principle: The Specification Section is the Deliverable - -The Planning Log is working notes. The Specification section is what matters. - -As you discuss with the user: -1. Capture in the Planning Log -2. **Immediately** distill validated information into the Specification -3. The Specification grows more complete with each exchange -4. When Specification is complete, formal planning can begin - -## 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 - -Draft planning is complete when the **Specification section** contains: -- [ ] Clear description of WHAT we're building and WHY -- [ ] Scope boundaries (in/out) -- [ ] Edge cases implementation needs to handle -- [ ] Testing ideas and acceptance criteria -- [ ] Approach guidance (if needed - this varies by feature) -- [ ] No blocking open questions remaining - -The right level of detail varies. Some features need detailed HOW guidance; others just need clear WHAT/WHY and can leave implementation to figure out the approach. The draft process is about finding that line. - -**Transition process**: -1. Review the Specification section together -2. User confirms it contains everything needed -3. Create formal `plan.md` by structuring the Specification into phases/tasks -4. Keep `draft-plan.md` for reference (the "why" behind decisions) - -**The Specification is standalone** - formal planning should not require going back to source discussion documents. Everything needed is in the draft. - -## Building Through Collaboration - -During draft planning, you are **building** the specification through discussion. When information is missing, ask. - -After context refresh: -- **If the draft exists**: Read it. Trust it. The Specification section has the detail you've lost. -- **If no draft exists**: You've lost the planning conversation. Be honest about that and ask again for what you need. 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 From 95f2c9638be4f616f3df342aa28a6153ec47ba55 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 10 Dec 2025 22:09:21 +0000 Subject: [PATCH 10/11] Remove time estimates from task design (5-30 min) --- skills/technical-planning/references/formal-planning.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/skills/technical-planning/references/formal-planning.md b/skills/technical-planning/references/formal-planning.md index d482cd48f..1002e4588 100644 --- a/skills/technical-planning/references/formal-planning.md +++ b/skills/technical-planning/references/formal-planning.md @@ -39,7 +39,6 @@ Break into logical phases: 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 @@ -75,7 +74,6 @@ Verify: **Each task should**: - Be a single TDD cycle - Have micro acceptance (specific test name) -- Take 5-30 minutes - Do one clear thing **One task = One TDD cycle**: write test → implement → pass → commit From a3c729799170dbab92ade27b2386bcfb6644e0c7 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 10 Dec 2025 22:15:41 +0000 Subject: [PATCH 11/11] Add draft/formal planning path choice to start-planning command --- commands/start-planning.md | 48 ++++++++++++++++++++++++++++---------- 1 file changed, 36 insertions(+), 12 deletions(-) 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