commit 166ae1e87af215dcff29d83f562f2a0fa8652e0d Author: Zhongwei Li Date: Sun Nov 30 08:44:25 2025 +0800 Initial commit diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..3d9d4e9 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "name": "handbook-structured-plan-mode", + "description": "Structured planning methodology for complex feature implementations through systematic task decomposition", + "version": "1.12.0", + "author": { + "name": "nikiforovall", + "url": "https://github.com/nikiforovall" + }, + "skills": [ + "./skills/structured-plan-mode" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..d43488a --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# handbook-structured-plan-mode + +Structured planning methodology for complex feature implementations through systematic task decomposition diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..8b680c2 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,61 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:NikiforovAll/claude-code-rules:plugins/handbook-structured-plan-mode", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "0bd4057e1926aaf846e66f9f5f69a77bdd7f57cd", + "treeHash": "438681512ac399720f26e7099674e3db1640697cf3cf3302fe99104a05f5677f", + "generatedAt": "2025-11-28T10:12:16.334272Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "handbook-structured-plan-mode", + "description": "Structured planning methodology for complex feature implementations through systematic task decomposition", + "version": "1.12.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "74d74afa4833ffe1e8687ef0f4cc6340de68ec95cfd684cda6e64448fcdeabf5" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "820c73a1c5d6124b86fa5648fe7af63e0fbb7b45b08f7e1bb15063e541f8352b" + }, + { + "path": "skills/structured-plan-mode/SKILL.md", + "sha256": "8103e830ee79fee2cb16a67225d9f454a4513126b141fa0769ad8b9129c4fa36" + }, + { + "path": "skills/structured-plan-mode/references/task-planning-guide.md", + "sha256": "cb4fe8da0d03e96a62dc885287335b347fc07379c3cd0a3bdbb07a7b0ff53147" + }, + { + "path": "skills/structured-plan-mode/references/usage-guide.md", + "sha256": "cb4fe8da0d03e96a62dc885287335b347fc07379c3cd0a3bdbb07a7b0ff53147" + }, + { + "path": "skills/structured-plan-mode/assets/task-template.md", + "sha256": "4af7a85fc8dfe55fc86a242e9c082eafcfd55ddacc1fbb87ba43e80c8f587580" + }, + { + "path": "skills/structured-plan-mode/assets/plan-template.md", + "sha256": "9c4d379c02df552f324488e06cc873cf38fcb35bd792a5a65a8c8e7ff5e0ad9c" + } + ], + "dirSha256": "438681512ac399720f26e7099674e3db1640697cf3cf3302fe99104a05f5677f" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/structured-plan-mode/SKILL.md b/skills/structured-plan-mode/SKILL.md new file mode 100644 index 0000000..e3fd9c9 --- /dev/null +++ b/skills/structured-plan-mode/SKILL.md @@ -0,0 +1,366 @@ +--- +name: structured-plan-mode +description: This skill should be used when planning and tracking complex feature implementations that require systematic task decomposition. Use this skill to break down large features into manageable, well-documented tasks with clear dependencies, action items, and success criteria. The skill provides a structured template and methodology for iterative planning and tracking throughout implementation. +--- + +# Structured Plan Mode Skill + +## Purpose + +This skill provides a structured approach for planning and tracking complex feature implementations through systematic task decomposition. It helps break down large, multi-component features into manageable tasks with clear goals, dependencies, and success criteria. + +## When to Use This Skill + +Use this skill when: +- **Complex features**: Features requiring multiple components or integration points +- **Multi-step implementations**: Work spanning several days with interdependent tasks +- **Pattern-setting work**: Features that will establish patterns for future development +- **Research required**: Work where multiple approaches need evaluation + +Do NOT use this skill for: +- Simple bug fixes +- Trivial feature additions +- One-off scripts or experiments +- Work with single, clear implementation path + +## How to Use the Skill + +**IMPORTANT**: This is a PHASED approach. Complete each phase BEFORE moving to the next. + +### Phase 1: Initial Setup + +**Actions:** +1. Create `.plans/[feature-name]/` directory (in current project directory) +2. Copy `assets/plan-template.md` to `.plans/[feature-name]/plan.md` +3. Create `.plans/[feature-name]/tasks/` directory for task files +4. Replace `[Feature Name]` with your feature name in plan.md +5. Fill in basic overview and context +6. Create Research section with: + - Goal + - Context + - Strategy Proposals (leave empty for now) + - **Leave "Selected Approach" EMPTY** +7. Create a todo list by using TodoWrite based on the phases below + + +**TodoWrite tracks ONLY phases 1-4:** +``` +- [ ] Phase 1: Setup template with Research section +- [ ] Phase 2: Conduct research and iterate with user +- [ ] Phase 3: Finalize selected approach +- [ ] Phase 4: Create implementation tasks (T01-T0N) +``` + +**Mark Phase 1 as completed in TodoWrite** + +**Output**: Skeleton plan document with Research section defined and todo list created for phases 1-4 + +--- + +### Phase 2: Conduct Research and Iterate with User + +**Research Process (Iterative):** +1. **Explore codebase**: Read relevant files, find similar patterns +2. **Document findings incrementally**: Add to "Key Findings" as you discover +3. **Identify 2-3 approach options**: Add to "Strategy Proposals" section +4. **ITERATE with user on EACH proposal**: + - Present each proposal with trade-offs (pros/cons) + - Use `AskUserQuestion` to clarify requirements and constraints + - **User may correct assumptions** - update research based on feedback + - Refine understanding through questions (typically 3-5 questions, but quality over quantity) + - **If user strongly prefers one approach early**, you may skip detailed discussion of remaining options +5. **Proactively ask if research is complete**: Once you've explored all options and answered clarifying questions, explicitly ask: "Are you ready to select an approach?" + +**CRITICAL**: +- This is an ITERATIVE process - expect back-and-forth discussion on each proposal +- Use AskUserQuestion frequently to refine understanding +- Don't wait for user to say research is done - ASK them proactively + +**Mark Phase 2 as completed in TodoWrite when user confirms that research is complete** + +**Output**: Research with 2-3 Strategy Proposals documented and reviewed with user + +--- + +### Phase 3: Finalize Selected Approach + +**Actions:** +1. **Ask the user to select an approach** using AskUserQuestion (present the 2-3 researched approaches as formal selection options) +2. **Once user confirms their selection**, fill "Selected Approach" section with: + - **Decision**: Which approach was selected (must match user's confirmed preference) + - **Rationale**: Why this approach was chosen over alternatives + - **Key Findings**: Summarize important discoveries from research + - **Implementation Plan**: High-level steps (5-7 bullet points) +3. Mark all research action items as [x] completed +4. Change research status to βœ… **Completed** +5. Update Progress Summary to show research complete + +**Mark Phase 3 as completed in TodoWrite once Selected Approach section is fully documented** + +**Output**: Research fully documented with clear decision and rationale + +--- + +### Phase 4: Create Implementation Tasks (ONLY AFTER Phase 1-3 Complete) + +**IMPORTANT**: Before creating tasks, read `references/task-planning-guide.md` to understand: +- How to break down work into appropriate task sizes +- Task file structure and required sections +- Best practices for defining clear requirements and action items +- How to set proper dependencies between tasks + +**Actions:** +**NOW create T01, T02, T03, ...T0N** as separate files in `.plans/[feature-name]/tasks/` based on selected approach + +- Number of tasks depends on complexity (simple: 1-2, medium: 3-5, complex: 5+) +- Break down into manageable chunks (2-5 days each) + +**Step-by-Step: Creating a Task File** + +For each task you need to create: + +1. **Copy the template**: + ```bash + cp [path-to-task-template.md] .plans/[feature-name]/tasks/T01.md + ``` +2. **Update task header**: Replace `T0X` with actual task number (T01, T02, etc.) +3. **Fill in core sections**: + - Goal: One clear, measurable objective + - Context: How it relates to the feature and selected approach + - Requirements: Detailed specifications with implementation steps + - Action Items: Specific checkboxes for work to complete +4. **Update metadata**: Set Status (🟑 Planned), Effort (Small/Medium/Large), Blocked By +5. **Add to Progress Summary**: Update plan.md with link: `- [ ] [**T01**: Task Name](tasks/T01.md) - Status: 🟑 Planned` + +**Mark Phase 4 as completed in TodoWrite** + +**Output**: Complete task breakdown (T01.md - T0N.md files) in tasks/ folder, all linked from plan.md Progress Summary + +--- + +### Phase 5: Working with Tasks (Implementation) + +**Note**: Phase 5 is NOT tracked in TodoWrite. Track progress directly in task files and plan.md. + +**IMPORTANT**: Before starting work on ANY task, read `references/task-planning-guide.md` for: +- Task structure guidance and best practices +- How to maintain task files during execution +- Examples of effective task documentation +- Common pitfalls to avoid + +**When to consult task-planning-guide.md:** +- Before starting a new task (every time) +- When unclear about task file structure or what to document +- When encountering challenges during task execution +- When adding new tasks mid-implementation + +#### Task Execution Discipline + +**CRITICAL RULE**: Work on ONE task at a time. Do NOT start the next task until the current task is FULLY completed. + +**Task Status Flow:** +1. 🟑 **Planned** β†’ Task created but not started +2. 🟒 **In Progress** β†’ Currently working on this task (only ONE task should be in this state) +3. βœ… **Completed** β†’ All action items done, both locations updated, Execution Summary filled +4. πŸ”΄ **Blocked** β†’ Cannot proceed due to dependency or external issue (move to next task until unblocked) + +#### Task Lifecycle: Step-by-Step + +**Starting a Task:** +1. **Read `references/task-planning-guide.md`** - Review relevant sections before beginning work +2. Choose next task from plan.md Progress Summary (respecting dependencies) +3. Update status to 🟒 **In Progress** in TWO places: + - Task file metadata: `**Status**: 🟒 **In Progress**` + - plan.md Progress Summary: `- [ ] [**T01**: Task Name](tasks/T01.md) - Status: 🟒 In Progress` + +**During Task Execution:** +4. Work through Action Items, checking off boxes as you complete them: + ```markdown + - [x] Create API endpoint + - [x] Add request validation + - [ ] Add error handling ← Currently working here + - [ ] Write tests + ``` +5. Update task file in real-time as work progresses +6. If you discover new requirements, add them to Action Items + +**Completing a Task:** +7. Verify ALL action items are checked: `[x]` +8. Fill in "Execution Summary" section in task file: + ```markdown + ## Execution Summary + **Completed**: 2025-01-08 14:30 + + **What was implemented**: + - Added /api/users endpoint with validation + - Implemented error handling for edge cases + + **Challenges encountered**: + - Had to refactor auth middleware to support new endpoint + ``` +9. Update status to βœ… **Completed** in TWO places: + - Task file metadata: `**Status**: βœ… **Completed**` + - plan.md Progress Summary: `- [x] [**T01**: Task Name](tasks/T01.md) - Status: βœ… Completed` +10. **Explicitly ask user**: "Task T01 is complete. Ready to move to T02?" +11. **ONLY after user confirms** proceed to next task + +#### Dual-Tracking Example + +When completing T01, you must update BOTH locations: + +**In `tasks/T01.md`** (lines 7-9): +```markdown +**Status**: βœ… **Completed** +**Effort**: Medium +**Blocked By**: None +``` + +**In `plan.md` Progress Summary** (line ~18): +```markdown +- [x] [**T01**: Add API endpoint](tasks/T01.md) - Status: βœ… Completed +``` + +**Why dual-tracking?** +- plan.md provides high-level overview of all tasks at a glance +- Task files provide detailed implementation notes for deep dives +- Both serve different purposes and audiences + +#### Handling Blocked Tasks + +If you cannot complete a task: +1. Update status to πŸ”΄ **Blocked** in both locations +2. Update "Blocked By" field in task file metadata +3. Document blocking reason in task file +4. Move to next non-blocked task +5. Return when blocker is resolved + +#### Discovering New Tasks Mid-Implementation + +If you discover additional work during Phase 5: +1. Create new task file (e.g., `T06.md`) in tasks/ directory +2. Fill in all sections using task-template.md +3. Add link to plan.md Progress Summary +4. Update dependent tasks if needed + +--- + +**Remember**: ONE task at a time. Complete it FULLY (all checkboxes, both locations updated, Execution Summary filled), then ASK USER for confirmation before moving to the next. + +--- + +### Phase 6: Post-Implementation Review + +**Note**: Phase 6 is NOT tracked in TodoWrite. Update the plan document directly. + +After feature completion: +- Fill in "Lessons Learned" section +- Verify all task statuses are accurate +- Document any technical debt or future work +- Review what went well and what could improve + +## Workflow Summary + +**TodoWrite tracks ONLY phases 1-4 (not subtasks):** +``` +- [ ] Phase 1: Setup template with Research section +- [ ] Phase 2: Conduct research and iterate with user +- [ ] Phase 3: Finalize selected approach +- [ ] Phase 4: Create implementation tasks (T01-T0N) +``` + +**Phase-by-Phase Workflow:** + +1. **Phase 1 - Setup**: + - Create `.plans/[feature-name]/` and `.plans/[feature-name]/tasks/` directories + - Copy plan-template.md to `.plans/[feature-name]/plan.md` + - Create Research section ONLY in plan.md + - DO NOT create T01, T02, T03 task files yet + - Mark Phase 1 complete in TodoWrite + +2. **Phase 2 - Research & Iterate** (AskUserQuestion REQUIRED): + - Explore codebase, document findings in plan.md + - Present 2-3 approach options + - **Iterate on EACH proposal** via AskUserQuestion (discuss trade-offs, clarify constraints) + - User may correct assumptions - update research + - **If user strongly prefers one approach**, may skip detailed discussion of remaining options + - **Proactively ask**: "Are you ready to select an approach?" + - Mark Phase 2 complete when user confirms + +3. **Phase 3 - Finalize**: + - Present 2-3 researched approaches and ask user to select one + - Once user confirms, fill "Selected Approach" section in plan.md + - Mark research as βœ… Completed in plan.md + - Mark Phase 3 complete once documentation is done + +4. **Phase 4 - Create Tasks**: + - **Read `references/task-planning-guide.md` before creating tasks** + - NOW create T01.md, T02.md, T03.md, ...T0N.md files in `.plans/[feature-name]/tasks/` + - Copy task-template.md for each task file + - Fill in task details based on selected approach + - Number of tasks depends on complexity + - Update Progress Summary in plan.md with links to task files + - Mark Phase 4 complete in TodoWrite + +5. **Phase 5 - Implementation** (ONE task at a time): + - **Read `references/task-planning-guide.md` before starting EACH task** + - Work on ONE task until FULLY completed (all checkboxes, both locations updated, Execution Summary filled) + - Update status in TWO places: task file metadata AND plan.md Progress Summary + - Track progress: 🟑 Planned β†’ 🟒 In Progress β†’ βœ… Completed + - Check off action items as you complete them + - Fill Execution Summary before marking complete + - **Explicitly ask user for confirmation** before moving to next task + - ONLY after user confirms proceed to next task + +6. **Phase 6 - Review**: + - Document lessons learned in plan.md + + +## Key Patterns from Successful Use + +### Pattern 1: Follow Existing Patterns +During research phase, research existing similar features and match their architecture exactly. +**Benefit**: Consistent codebase, faster implementation, reduced bugs. + +### Pattern 2: Simplify When Possible +During research, look for ways to simplify (e.g., avoid unnecessary API calls). +**Benefit**: Reduced dependencies, better performance, easier maintenance. + +### Pattern 3: Discover Existing Implementations +Research phase may reveal the work is already done - mark task complete. +**Benefit**: Avoids duplicate work, leverages tested code. + +### Pattern 4: Document Design Decisions +During research phase, use the **"Selected Approach"** section to document WHY you chose one approach over alternatives. +Include: decision, rationale, key findings, and implementation plan. +**Benefit**: Future developers understand rationale, prevents second-guessing, provides clear starting point. + +### Pattern 5: Keep Tasks Focused +Break large tasks into smaller chunks that are independently testable. +**Benefit**: Steady progress, clear milestones, easier to parallelize. + +## Reference Materials + +**CRITICAL**: `references/task-planning-guide.md` is NOT just for planning - read it throughout implementation. + +**Read `references/task-planning-guide.md`:** +- **Phase 4**: Before creating task files (understand task structure, sizing, dependencies) +- **Phase 5**: Before starting EACH task (review best practices, avoid common pitfalls) +- **During execution**: When updating task files, adding action items, or documenting progress +- **When stuck**: Consult checklist for good task planning and common pitfalls section + +**Additional reference:** +- `references/usage-guide.md` - Detailed template section explanations + +--- + +**Remember**: +1. **TodoWrite tracks PHASES** - not individual subtasks +2. **Phases are sequential** - complete Phase 1 before Phase 2, etc. +3. **Phase 2 is iterative** - use AskUserQuestion multiple times, expect back-and-forth +4. **User confirms approach** - do NOT fill "Selected Approach" until user confirms +5. **No premature planning** - T01-T0N created in Phase 4 +6. **Task count is flexible** - create as many as needed (T01, T02, ...T0N) +7. **ONE task at a time** - Complete current task FULLY (all checkboxes, both locations, Execution Summary) before starting next +8. **Dual-tracking required** - Update status in BOTH task file AND plan.md +9. **Explicit user confirmation** - Ask user for approval before moving to next task +10. **Read task-planning-guide.md** - Before Phase 4, before EACH task in Phase 5, and when stuck diff --git a/skills/structured-plan-mode/assets/plan-template.md b/skills/structured-plan-mode/assets/plan-template.md new file mode 100644 index 0000000..3c6dd37 --- /dev/null +++ b/skills/structured-plan-mode/assets/plan-template.md @@ -0,0 +1,135 @@ +# [Feature Name] - Plan + +> **Template Purpose**: This template provides a structured approach for planning and tracking complex feature implementations. Copy this template to `.plans/[feature-name]/plan.md` and adapt it for your feature. +> +> **Task Files**: Create individual task files in `.plans/[feature-name]/tasks/` using `task-template.md` as your starting point. + +--- + + +### Progress Summary + +* [ ] **Research & Strategy Selection** 🟑 Planned + - Explore existing patterns + - Evaluate approach options + - Select and document strategy + + +* [ ] [**T01**: [First Implementation Task]](tasks/T01.md) - Status: 🟑 Planned +* [ ] [**T02**: [Second Implementation Task]](tasks/T02.md) - Status: 🟑 Planned +* [ ] [**T03**: [Third Implementation Task]](tasks/T03.md) - Status: 🟑 Planned + + + + + +--- + +## Research & Strategy Selection +**Status**: 🟑 **Planned** + +### Goal +[Describe the research objective - understand existing patterns, identify approaches, evaluate alternatives] + +### Context +[Explain why this research is needed and what questions need answering] + +**Action Items**: + +- [ ] Review existing patterns in codebase +- [ ] Analyze relevant APIs/data sources +- [ ] Identify 2-4 viable approach options +- [ ] Present findings and trade-offs to user +- [ ] Get user confirmation on selected approach + +### Strategy Proposals + +> **Fill this during research as you discover options** + +**Option A: [Approach Name]** +- Description: [Brief description] +- Pros: [Benefits] +- Cons: [Drawbacks] + +**Option B: [Approach Name]** +- Description: [Brief description] +- Pros: [Benefits] +- Cons: [Drawbacks] + +**Option C: [Approach Name]** (if applicable) +- Description: [Brief description] +- Pros: [Benefits] +- Cons: [Drawbacks] + +### Selected Approach + +> **IMPORTANT**: Fill this section AFTER user confirms the selected strategy + +**Decision**: [Which approach was selected - Option A/B/C or hybrid] + +**Rationale**: [Why this approach was chosen over alternatives] + +**Key Findings**: +- [Finding 1 from research] +- [Finding 2 from research] +- [Finding 3 from research] + +**Implementation Plan**: +- [High-level step 1] +- [High-level step 2] +- [High-level step 3] +- [High-level step 4] +- [High-level step 5] + +### Dependencies +- [External dependency 1] +- [External dependency 2] + +### Related Files +- `[file/path/here]` - Description + +--- + +## Implementation Tasks + +> Task files will be created in the `tasks/` subfolder during Phase 4 of the structured plan mode workflow. + +--- + +## Lessons Learned (Post-Implementation) + +> Fill this section out after completing the feature + +### What Went Well +- [Success 1] +- [Success 2] + +### What Could Be Improved +- [Area for improvement 1] +- [Area for improvement 2] + +### Unexpected Challenges +- [Challenge 1 and how it was resolved] +- [Challenge 2 and how it was resolved] + +### Recommendations for Future Features +- [Recommendation 1] +- [Recommendation 2] + +--- + + + +## Task Status Legend +- πŸ”΄ **Blocked**: Requires external dependency or decision +- 🟑 **Planned**: Ready to implement +- 🟒 **In Progress**: Currently being worked on +- βœ… **Completed**: Done + +## Change Log + +- **YYYY-MM-DD HH:MM**: Initial task breakdown +- **YYYY-MM-DD HH:MM**: Research completed - [selected approach] +- **YYYY-MM-DD HH:MM**: T0X completed - [brief description of what was done] +- **YYYY-MM-DD HH:MM**: Updated T0Y based on new findings + diff --git a/skills/structured-plan-mode/assets/task-template.md b/skills/structured-plan-mode/assets/task-template.md new file mode 100644 index 0000000..7ed4712 --- /dev/null +++ b/skills/structured-plan-mode/assets/task-template.md @@ -0,0 +1,80 @@ +# T0X: [Task Name] + +> **Template Purpose**: Copy this template for each implementation task (T01, T02, T03, etc.) in your `.plans/[feature-name]/tasks/` folder. + +--- + +**Status**: 🟑 **Planned** +**Effort**: [Small/Medium/Large] +**Blocked By**: [List any blocking tasks or dependencies] + +## Goal + +[Describe what this task achieves - one clear, measurable objective] + +## Context + +[Explain how this fits into the overall feature, why it's needed, and how it relates to the selected approach from Research] + +## Requirements + +### 1. [Requirement Category 1] + +[Describe the requirement] + +**Key Considerations**: +- [Consideration 1] +- [Consideration 2] + +### 2. [Requirement Category 2] + +[Describe the requirement] + +**Implementation Details**: +- Step 1: [Description] +- Step 2: [Description] +- Step 3: [Description] + +### 3. Integration Points + +[Describe where this integrates with existing systems] + +## Action Items + +- [ ] [Specific action item 1] +- [ ] [Specific action item 2] +- [ ] [Specific action item 3] +- [ ] Add error handling +- [ ] Add telemetry/logging +- [ ] Write tests + +## Test Scenarios + +- [ ] Happy path: [Description] +- [ ] Error case: [Description] +- [ ] Edge case: [Description] +- [ ] Performance: [Description] + +## Dependencies + +- [Dependency 1] +- [Dependency 2] + +## Related Files + +- `[file/path]` - Description +- `[file/path]` - Description + +## Execution Summary + + + +**Completed**: [YYYY-MM-DD HH:MM] + +**What was implemented**: +- [Key change 1] +- [Key change 2] + +**Challenges encountered**: +- [Challenge 1 and resolution] + diff --git a/skills/structured-plan-mode/references/task-planning-guide.md b/skills/structured-plan-mode/references/task-planning-guide.md new file mode 100644 index 0000000..d15090b --- /dev/null +++ b/skills/structured-plan-mode/references/task-planning-guide.md @@ -0,0 +1,348 @@ +# Task Planning Guide + +> This guide explains how to effectively plan and track complex feature implementations using the task template approach. + +## Overview + +The task template approach is designed to help you systematically break down complex features into manageable, well-documented tasks. This guide explains the methodology behind the template and how to use it effectively. + +## Core Philosophy + +### 1. Research Before Implementation +Always start with a **Research** phase: +- Understand existing patterns in the codebase +- Evaluate multiple approaches before committing +- Document findings and rationale for decisions +- Create a clear implementation plan + +**Why**: Prevents false starts, reduces rework, and ensures consistency with existing patterns. + +### 2. Iterative Documentation +Update task documentation throughout implementation: +- Mark tasks as completed when finished +- Document actual implementation details (not just plans) +- Record lessons learned and unexpected challenges +- Keep success criteria current + +**Why**: Creates valuable reference material for future similar features. + +### 3. Interactive Clarification +Ask clarifying questions proactively when planning or implementing: +- When multiple valid approaches exist +- When requirements are ambiguous or unclear +- When design decisions affect architecture +- When user preferences matter for implementation + +**Why**: Prevents wasted effort on wrong assumptions and ensures alignment with user needs. + +**Tool**: Use the **AskUserQuestion** tool to gather decisions during execution. + +## Template Structure Explained + +### Task Metadata +```markdown +**Status**: 🟑 **Planned** +**Effort**: Medium +``` + +**Purpose**: Quick visibility into task state and scope. + +**Best Practices**: +- Update status in real-time as work progresses +- Use actual effort estimates from similar past work + +### Goal Section +```markdown +### Goal +[Clear, one-sentence objective] +``` + +**Purpose**: Ensures everyone understands what success looks like. + +**Best Practices**: +- Make it specific and measurable +- Focus on outcomes, not activities +- Example: "Implement citation-based linking between DI and SPO using driveId/itemId matching" + +### Context Section +```markdown +### Context +[Why this task exists and how it fits into the larger feature] +``` + +**Purpose**: Provides background and motivation. + +**Best Practices**: +- Explain dependencies on other tasks +- Reference related features or patterns +- Highlight any constraints or assumptions + +### Requirements Section +```markdown +### Requirements +#### 1. [Requirement Category] +[Detailed description with code examples] +``` + +**Purpose**: Breaks down the work into concrete, actionable pieces. + +**Best Practices**: +- Use numbered categories for organization +- Include code snippets showing intended design +- Specify integration points with existing code +- Address non-functional requirements (performance, security, etc.) + +### Action Items +```markdown +### Action Items +- [ ] [Specific, actionable task] +- [ ] [Another task] +``` + +**Purpose**: Creates a checklist for implementation. + +**Best Practices**: +- Make items specific and testable +- Include cross-cutting concerns (error handling, logging, tests) +- Check off items as you complete them +- Add new items as they're discovered + +### Test Scenarios +```markdown +### Test Scenarios +- [ ] Happy path: [Description] +- [ ] Error case: [Description] +``` + +**Purpose**: Ensures comprehensive testing coverage. + +**Best Practices**: +- Cover happy path, error cases, and edge cases +- Include performance/load testing scenarios +- Reference specific test files once written + +### Dependencies +```markdown +### Dependencies +- [External dependency or blocking task] +``` + +**Purpose**: Makes blocking relationships explicit. + +**Best Practices**: +- List both internal (other tasks) and external dependencies +- Link to related tasks using markdown +- Update when dependencies are resolved + +### Related Files +```markdown +### Related Files +- `path/to/file.cs` - Description of relevance +``` + +**Purpose**: Creates navigable links to relevant code. + +**Best Practices**: +- Include both files to read and files to modify +- Add brief descriptions of relevance +- Update as implementation progresses + +## How to Use the Template + +### Step 1: Set Up Directory Structure +```bash +# Create plan directory and tasks subfolder +mkdir -p .plans/[feature-name]/tasks + +# Copy plan template +cp assets/plan-template.md .plans/[feature-name]/plan.md +``` + +### Step 2: Fill in the Overview +- Replace `[Feature Name]` throughout plan.md +- Write a brief feature overview +- Identify the main phases of work + +### Step 3: Create Research Section +**Always start here**, even for "obvious" features: +1. List what you need to research in plan.md +2. Document similar patterns in the codebase +3. Evaluate multiple approaches (list pros/cons for each - 2-3 options) +4. **Ask clarifying questions** via AskUserQuestion if approaches have different trade-offs +5. **Get user confirmation** on selected approach +6. **Document final decision** in "Selected Approach" section +7. Create high-level implementation plan (5-7 steps) + +### Step 4: Break Down Implementation Tasks (AFTER Research Complete) +For each major component: +1. Create individual task files (T01.md, T02.md, T03.md, ...T0N.md) in `.plans/[feature-name]/tasks/` +2. Copy `assets/task-template.md` for each task file +3. Fill in: Goal, Context, Requirements, Action Items, Test Scenarios, Dependencies +4. Update task metadata: Status, Effort, Blocked By +5. Add links to task files in plan.md Progress Summary + +**Task File Organization**: +``` +.plans/[feature-name]/ +β”œβ”€β”€ plan.md # Main plan with Research and Progress Summary +└── tasks/ + β”œβ”€β”€ T01.md # First implementation task + β”œβ”€β”€ T02.md # Second implementation task + └── T0N.md # Nth implementation task +``` + +**Step-by-Step: Creating a Task File** + +For each task you need to create: + +1. **Copy the template**: + ```bash + cp [path-to-task-template.md] .plans/[feature-name]/tasks/T01.md + ``` +2. **Update task header**: Replace `T0X` with actual task number (T01, T02, etc.) +3. **Fill in core sections**: + - Goal: One clear, measurable objective + - Context: How it relates to the feature and selected approach + - Requirements: Detailed specifications with implementation steps + - Action Items: Specific checkboxes for work to complete +4. **Update metadata**: Set Status (🟑 Planned), Effort (Small/Medium/Large), Blocked By +5. **Add to Progress Summary**: Update plan.md with link: `- [ ] [**T01**: Task Name](tasks/T01.md) - Status: 🟑 Planned` + +**Tips**: +- Number of tasks depends on complexity (simple: 1-2, medium: 3-5, complex: 5+) +- Keep tasks focused (ideally 2-5 days each) +- Tasks should be independently testable +- Consider parallelization opportunities +- ALL tasks should align with the approach selected in research + +**Why**: Provides clear definition of "done" and prevents scope creep. Separate task files keep each concern focused and easy to navigate. + +## Common Pitfalls to Avoid + +### 1. Skipping Research +❌ **Don't**: Jump straight into implementation. +βœ… **Do**: Always start with research, even for "simple" features. + +**Why**: Prevents rework and ensures consistency with existing patterns. + +### 2. Vague Requirements +❌ **Don't**: "Add Q&A feature" +βœ… **Do**: "Implement Q&A feature allowing users to post questions and receive answers, with upvote functionality and moderation tools." + +**Why**: Clear requirements prevent misunderstandings and scope creep. + +### 3. Ignoring Dependencies +❌ **Don't**: Start Task 2 before Task 1 is complete. +βœ… **Do**: Explicitly list and track dependencies. + +**Why**: Prevents blocked work and wasted effort. + +### 4. Not Updating Documentation +❌ **Don't**: Leave task docs outdated after implementation. +βœ… **Do**: Update tasks as you work, marking completions and adding discoveries. + +**Why**: Creates accurate reference material for future work. + +### 5. Over-Committing to Advanced Features +❌ **Don't**: Try to implement all tasks at once. +βœ… **Do**: Focus on core functionality first, defer advanced features. + +**Why**: Enables earlier delivery and reduces risk. + +### 6. Assuming Instead of Asking +❌ **Don't**: Make assumptions about requirements, architecture choices, or user preferences. +βœ… **Do**: Use **AskUserQuestion** tool to clarify ambiguities before committing to an approach. + +**Why**: Prevents wasted effort on wrong assumptions and rework. + +**Example scenarios**: +- "Should we use library A (faster) or library B (more features)?" +- "Which authentication method do you prefer: OAuth, JWT, or session-based?" +- "Do you want to support real-time updates or is polling acceptable?" + +## Checklist for Good Task Planning + +Use this checklist when creating or reviewing task documentation: + +### Research Phase +- [ ] Identified similar features/patterns in codebase +- [ ] Evaluated multiple approaches with pros/cons +- [ ] **Asked clarifying questions** using AskUserQuestion tool as needed +- [ ] **Documented final decision** in "Selected Approach" section +- [ ] Included rationale explaining why chosen approach is best +- [ ] Listed key findings from research +- [ ] Created high-level implementation plan + +### Task Definition +- [ ] Clear, measurable goal +- [ ] Context explaining why task exists +- [ ] Detailed requirements with code examples +- [ ] Specific action items +- [ ] Comprehensive test scenarios +- [ ] Dependencies explicitly listed +- [ ] Related files identified + +### Planning +- [ ] Tasks are appropriately sized (2-5 days ideal) +- [ ] Dependencies are correct and up-to-date +- [ ] Sprint/phase groupings are logical +- [ ] Success criteria are measurable +- [ ] Implementation order makes sense + +### Maintenance +- [ ] Task statuses reflect reality +- [ ] Completed tasks show actual implementation +- [ ] New discoveries are documented +- [ ] Lessons learned are captured + +--- + +## Task File Structure + +When using separate task files, organize your work as follows: + +### Directory Structure +``` +.plans/[feature-name]/ +β”œβ”€β”€ plan.md # Main plan document +└── tasks/ # Task files directory + β”œβ”€β”€ T01.md # Individual task files + β”œβ”€β”€ T02.md + └── T0N.md +``` + +### plan.md Contents +- **Progress Summary**: Links to all task files with status +- **Research & Strategy Selection**: Full research documentation +- **Implementation Tasks**: Instructions for creating task files +- **Lessons Learned**: Post-implementation reflections + +### Task File Contents (T01.md, T02.md, etc.) +- **Metadata**: Status, Effort, Blocked By +- **Goal**: Clear, measurable objective +- **Context**: How it fits into the feature +- **Requirements**: Detailed specifications +- **Action Items**: Checklist of work to complete +- **Test Scenarios**: Testing requirements +- **Dependencies**: What must be done first +- **Related Files**: Code files to modify +- **Execution Summary**: Post-completion notes + +## Quick Start Checklist + +When starting a new feature: + +1. [ ] Create `.plans/[feature-name]/` and `.plans/[feature-name]/tasks/` directories +2. [ ] Copy `plan-template.md` to `.plans/[feature-name]/plan.md` +3. [ ] Fill in feature overview and goals in plan.md +4. [ ] Create Research section in plan.md and complete it first +5. [ ] Break down implementation into 2-5 day tasks +6. [ ] Create task files (T01.md, T02.md, etc.) using task-template.md +7. [ ] Link task files in plan.md Progress Summary +8. [ ] Define clear success criteria in each task file +9. [ ] Update task files and plan.md throughout implementation +10. [ ] Fill in lessons learned in plan.md when complete + +--- + +**Remember**: Good planning prevents poor performance. Invest time upfront in task breakdown and researchβ€”it pays dividends throughout implementation. diff --git a/skills/structured-plan-mode/references/usage-guide.md b/skills/structured-plan-mode/references/usage-guide.md new file mode 100644 index 0000000..d15090b --- /dev/null +++ b/skills/structured-plan-mode/references/usage-guide.md @@ -0,0 +1,348 @@ +# Task Planning Guide + +> This guide explains how to effectively plan and track complex feature implementations using the task template approach. + +## Overview + +The task template approach is designed to help you systematically break down complex features into manageable, well-documented tasks. This guide explains the methodology behind the template and how to use it effectively. + +## Core Philosophy + +### 1. Research Before Implementation +Always start with a **Research** phase: +- Understand existing patterns in the codebase +- Evaluate multiple approaches before committing +- Document findings and rationale for decisions +- Create a clear implementation plan + +**Why**: Prevents false starts, reduces rework, and ensures consistency with existing patterns. + +### 2. Iterative Documentation +Update task documentation throughout implementation: +- Mark tasks as completed when finished +- Document actual implementation details (not just plans) +- Record lessons learned and unexpected challenges +- Keep success criteria current + +**Why**: Creates valuable reference material for future similar features. + +### 3. Interactive Clarification +Ask clarifying questions proactively when planning or implementing: +- When multiple valid approaches exist +- When requirements are ambiguous or unclear +- When design decisions affect architecture +- When user preferences matter for implementation + +**Why**: Prevents wasted effort on wrong assumptions and ensures alignment with user needs. + +**Tool**: Use the **AskUserQuestion** tool to gather decisions during execution. + +## Template Structure Explained + +### Task Metadata +```markdown +**Status**: 🟑 **Planned** +**Effort**: Medium +``` + +**Purpose**: Quick visibility into task state and scope. + +**Best Practices**: +- Update status in real-time as work progresses +- Use actual effort estimates from similar past work + +### Goal Section +```markdown +### Goal +[Clear, one-sentence objective] +``` + +**Purpose**: Ensures everyone understands what success looks like. + +**Best Practices**: +- Make it specific and measurable +- Focus on outcomes, not activities +- Example: "Implement citation-based linking between DI and SPO using driveId/itemId matching" + +### Context Section +```markdown +### Context +[Why this task exists and how it fits into the larger feature] +``` + +**Purpose**: Provides background and motivation. + +**Best Practices**: +- Explain dependencies on other tasks +- Reference related features or patterns +- Highlight any constraints or assumptions + +### Requirements Section +```markdown +### Requirements +#### 1. [Requirement Category] +[Detailed description with code examples] +``` + +**Purpose**: Breaks down the work into concrete, actionable pieces. + +**Best Practices**: +- Use numbered categories for organization +- Include code snippets showing intended design +- Specify integration points with existing code +- Address non-functional requirements (performance, security, etc.) + +### Action Items +```markdown +### Action Items +- [ ] [Specific, actionable task] +- [ ] [Another task] +``` + +**Purpose**: Creates a checklist for implementation. + +**Best Practices**: +- Make items specific and testable +- Include cross-cutting concerns (error handling, logging, tests) +- Check off items as you complete them +- Add new items as they're discovered + +### Test Scenarios +```markdown +### Test Scenarios +- [ ] Happy path: [Description] +- [ ] Error case: [Description] +``` + +**Purpose**: Ensures comprehensive testing coverage. + +**Best Practices**: +- Cover happy path, error cases, and edge cases +- Include performance/load testing scenarios +- Reference specific test files once written + +### Dependencies +```markdown +### Dependencies +- [External dependency or blocking task] +``` + +**Purpose**: Makes blocking relationships explicit. + +**Best Practices**: +- List both internal (other tasks) and external dependencies +- Link to related tasks using markdown +- Update when dependencies are resolved + +### Related Files +```markdown +### Related Files +- `path/to/file.cs` - Description of relevance +``` + +**Purpose**: Creates navigable links to relevant code. + +**Best Practices**: +- Include both files to read and files to modify +- Add brief descriptions of relevance +- Update as implementation progresses + +## How to Use the Template + +### Step 1: Set Up Directory Structure +```bash +# Create plan directory and tasks subfolder +mkdir -p .plans/[feature-name]/tasks + +# Copy plan template +cp assets/plan-template.md .plans/[feature-name]/plan.md +``` + +### Step 2: Fill in the Overview +- Replace `[Feature Name]` throughout plan.md +- Write a brief feature overview +- Identify the main phases of work + +### Step 3: Create Research Section +**Always start here**, even for "obvious" features: +1. List what you need to research in plan.md +2. Document similar patterns in the codebase +3. Evaluate multiple approaches (list pros/cons for each - 2-3 options) +4. **Ask clarifying questions** via AskUserQuestion if approaches have different trade-offs +5. **Get user confirmation** on selected approach +6. **Document final decision** in "Selected Approach" section +7. Create high-level implementation plan (5-7 steps) + +### Step 4: Break Down Implementation Tasks (AFTER Research Complete) +For each major component: +1. Create individual task files (T01.md, T02.md, T03.md, ...T0N.md) in `.plans/[feature-name]/tasks/` +2. Copy `assets/task-template.md` for each task file +3. Fill in: Goal, Context, Requirements, Action Items, Test Scenarios, Dependencies +4. Update task metadata: Status, Effort, Blocked By +5. Add links to task files in plan.md Progress Summary + +**Task File Organization**: +``` +.plans/[feature-name]/ +β”œβ”€β”€ plan.md # Main plan with Research and Progress Summary +└── tasks/ + β”œβ”€β”€ T01.md # First implementation task + β”œβ”€β”€ T02.md # Second implementation task + └── T0N.md # Nth implementation task +``` + +**Step-by-Step: Creating a Task File** + +For each task you need to create: + +1. **Copy the template**: + ```bash + cp [path-to-task-template.md] .plans/[feature-name]/tasks/T01.md + ``` +2. **Update task header**: Replace `T0X` with actual task number (T01, T02, etc.) +3. **Fill in core sections**: + - Goal: One clear, measurable objective + - Context: How it relates to the feature and selected approach + - Requirements: Detailed specifications with implementation steps + - Action Items: Specific checkboxes for work to complete +4. **Update metadata**: Set Status (🟑 Planned), Effort (Small/Medium/Large), Blocked By +5. **Add to Progress Summary**: Update plan.md with link: `- [ ] [**T01**: Task Name](tasks/T01.md) - Status: 🟑 Planned` + +**Tips**: +- Number of tasks depends on complexity (simple: 1-2, medium: 3-5, complex: 5+) +- Keep tasks focused (ideally 2-5 days each) +- Tasks should be independently testable +- Consider parallelization opportunities +- ALL tasks should align with the approach selected in research + +**Why**: Provides clear definition of "done" and prevents scope creep. Separate task files keep each concern focused and easy to navigate. + +## Common Pitfalls to Avoid + +### 1. Skipping Research +❌ **Don't**: Jump straight into implementation. +βœ… **Do**: Always start with research, even for "simple" features. + +**Why**: Prevents rework and ensures consistency with existing patterns. + +### 2. Vague Requirements +❌ **Don't**: "Add Q&A feature" +βœ… **Do**: "Implement Q&A feature allowing users to post questions and receive answers, with upvote functionality and moderation tools." + +**Why**: Clear requirements prevent misunderstandings and scope creep. + +### 3. Ignoring Dependencies +❌ **Don't**: Start Task 2 before Task 1 is complete. +βœ… **Do**: Explicitly list and track dependencies. + +**Why**: Prevents blocked work and wasted effort. + +### 4. Not Updating Documentation +❌ **Don't**: Leave task docs outdated after implementation. +βœ… **Do**: Update tasks as you work, marking completions and adding discoveries. + +**Why**: Creates accurate reference material for future work. + +### 5. Over-Committing to Advanced Features +❌ **Don't**: Try to implement all tasks at once. +βœ… **Do**: Focus on core functionality first, defer advanced features. + +**Why**: Enables earlier delivery and reduces risk. + +### 6. Assuming Instead of Asking +❌ **Don't**: Make assumptions about requirements, architecture choices, or user preferences. +βœ… **Do**: Use **AskUserQuestion** tool to clarify ambiguities before committing to an approach. + +**Why**: Prevents wasted effort on wrong assumptions and rework. + +**Example scenarios**: +- "Should we use library A (faster) or library B (more features)?" +- "Which authentication method do you prefer: OAuth, JWT, or session-based?" +- "Do you want to support real-time updates or is polling acceptable?" + +## Checklist for Good Task Planning + +Use this checklist when creating or reviewing task documentation: + +### Research Phase +- [ ] Identified similar features/patterns in codebase +- [ ] Evaluated multiple approaches with pros/cons +- [ ] **Asked clarifying questions** using AskUserQuestion tool as needed +- [ ] **Documented final decision** in "Selected Approach" section +- [ ] Included rationale explaining why chosen approach is best +- [ ] Listed key findings from research +- [ ] Created high-level implementation plan + +### Task Definition +- [ ] Clear, measurable goal +- [ ] Context explaining why task exists +- [ ] Detailed requirements with code examples +- [ ] Specific action items +- [ ] Comprehensive test scenarios +- [ ] Dependencies explicitly listed +- [ ] Related files identified + +### Planning +- [ ] Tasks are appropriately sized (2-5 days ideal) +- [ ] Dependencies are correct and up-to-date +- [ ] Sprint/phase groupings are logical +- [ ] Success criteria are measurable +- [ ] Implementation order makes sense + +### Maintenance +- [ ] Task statuses reflect reality +- [ ] Completed tasks show actual implementation +- [ ] New discoveries are documented +- [ ] Lessons learned are captured + +--- + +## Task File Structure + +When using separate task files, organize your work as follows: + +### Directory Structure +``` +.plans/[feature-name]/ +β”œβ”€β”€ plan.md # Main plan document +└── tasks/ # Task files directory + β”œβ”€β”€ T01.md # Individual task files + β”œβ”€β”€ T02.md + └── T0N.md +``` + +### plan.md Contents +- **Progress Summary**: Links to all task files with status +- **Research & Strategy Selection**: Full research documentation +- **Implementation Tasks**: Instructions for creating task files +- **Lessons Learned**: Post-implementation reflections + +### Task File Contents (T01.md, T02.md, etc.) +- **Metadata**: Status, Effort, Blocked By +- **Goal**: Clear, measurable objective +- **Context**: How it fits into the feature +- **Requirements**: Detailed specifications +- **Action Items**: Checklist of work to complete +- **Test Scenarios**: Testing requirements +- **Dependencies**: What must be done first +- **Related Files**: Code files to modify +- **Execution Summary**: Post-completion notes + +## Quick Start Checklist + +When starting a new feature: + +1. [ ] Create `.plans/[feature-name]/` and `.plans/[feature-name]/tasks/` directories +2. [ ] Copy `plan-template.md` to `.plans/[feature-name]/plan.md` +3. [ ] Fill in feature overview and goals in plan.md +4. [ ] Create Research section in plan.md and complete it first +5. [ ] Break down implementation into 2-5 day tasks +6. [ ] Create task files (T01.md, T02.md, etc.) using task-template.md +7. [ ] Link task files in plan.md Progress Summary +8. [ ] Define clear success criteria in each task file +9. [ ] Update task files and plan.md throughout implementation +10. [ ] Fill in lessons learned in plan.md when complete + +--- + +**Remember**: Good planning prevents poor performance. Invest time upfront in task breakdown and researchβ€”it pays dividends throughout implementation.