zhongwei/gh-nikiforovall-claude-code-rules-plugins-handbook-structured-plan-mode
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:44:25 +08:00
commit 166ae1e87a
8 changed files with 1353 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
.claude-plugin/plugin.json Normal file
View File

@@ -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"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# handbook-structured-plan-mode
Structured planning methodology for complex feature implementations through systematic task decomposition

61
plugin.lock.json Normal file
View File

@@ -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": []
}
}

366
skills/structured-plan-mode/SKILL.md Normal file
View File

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

135
skills/structured-plan-mode/assets/plan-template.md Normal file
View File

@@ -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 SECTION -->
### Progress Summary
* [ ] **Research & Strategy Selection** 🟡 Planned
- Explore existing patterns
- Evaluate approach options
- Select and document strategy
<!-- Task links will be added in Phase 4 - these are placeholders showing the format -->
* [ ] [**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
<!-- Add more task links (T04, T05, ...T0N) as needed based on complexity -->
<!-- END PROGRESS SECTION -->
---
## 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]
---
<!-- META_INFORMATION -->
## 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
<!-- META_INFORMATION -->

80
skills/structured-plan-mode/assets/task-template.md Normal file
View File

@@ -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
<!-- Fill this section after completing this task -->
**Completed**: [YYYY-MM-DD HH:MM]
**What was implemented**:
- [Key change 1]
- [Key change 2]
**Challenges encountered**:
- [Challenge 1 and resolution]

348
skills/structured-plan-mode/references/task-planning-guide.md Normal file
View File

@@ -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.

348
skills/structured-plan-mode/references/usage-guide.md Normal file
View File

@@ -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.