Initial commit

shavakan/docs-feature-plan.md

@@ -0,0 +1,197 @@
+---
+description: Create comprehensive strategic plan + context files (plan.md, context.md, tasks.md)
+---
+
+# Feature Plan - Strategic Planning and Documentation
+
+Create comprehensive implementation plans that prevent losing context during complex features.
+
+## Additional Instructions
+
+$ARGUMENTS
+
+---
+
+## Objective
+
+Create comprehensive implementation plans for complex features that prevent context loss during development. Research codebase, design strategic plan with phases and risks, generate planning files in features/ directory.
+
+**Output Structure:**
+```
+features/[task-name]/
+├── plan.md      # Comprehensive accepted plan
+├── context.md   # Key files, architectural decisions, integration points
+└── tasks.md     # Markdown checklist of work items
+```
+
+---
+
+## Execution
+
+### Phase 1: Research and Plan
+
+Analyze user requirements and research codebase for architecture, existing patterns, and integration points. Create comprehensive strategic plan including:
+
+- Executive summary (what and why)
+- Implementation phases with specific tasks
+- Risks and mitigation strategies
+- Success metrics and timeline estimates
+
+Reference specific file paths, function names, and existing patterns to follow.
+
+**Gate**: Present complete plan to user for review before creating files.
+
+### Phase 2: Confirm Approach
+
+Present the strategic plan with options:
+```
+Create feature plan files?
+
+□ Approve plan - Create files in features/ directory
+□ Revise approach - Adjust strategy before creating files
+□ Change scope - Modify phases or tasks
+□ Cancel
+```
+
+After approval, ask for task name (kebab-case format).
+
+**Gate**: User must approve plan and provide task name.
+
+### Phase 3: Generate Planning Files
+
+Create `features/[task-name]/` directory with three files:
+
+**plan.md** - Comprehensive implementation plan (executive summary, phases, tasks, risks, success metrics, timeline)
+
+**context.md** - Key files, architectural decisions, integration points, patterns to follow, next steps for resuming work
+
+**tasks.md** - Markdown checklist organized by phase, including testing and documentation tasks
+
+**Gate**: All files created successfully.
+
+### Phase 4: Report Results
+
+Summarize what was created: directory location, files generated, next steps for implementation. Remind user to keep context.md updated during implementation and mark tasks complete in tasks.md.
+
+---
+
+## File Format Examples
+
+### plan.md Format
+```markdown
+# [Feature Name] Implementation Plan
+
+## Executive Summary
+[2-3 sentences describing what and why]
+
+## Context
+- Current state
+- Why this change is needed
+- What problems it solves
+
+## Implementation Phases
+
+### Phase 1: [Name]
+**Goal:** [What this phase achieves]
+
+**Tasks:**
+1. Task description with file references
+2. Another task
+
+**Risks:**
+- Risk and mitigation
+
+### Phase 2: [Name]
+...
+
+## Success Metrics
+- How we know it's working
+- What to test
+
+## Timeline
+Estimated: X days/weeks
+```
+
+### context.md Format
+```markdown
+# [Feature Name] - Context & Key Decisions
+
+**Last Updated:** [timestamp]
+
+## Key Files
+- `path/to/file.ts` - Purpose and why it matters
+- `path/to/another.ts` - Purpose
+
+## Architectural Decisions
+1. **Decision:** What we decided
+   **Rationale:** Why we decided it
+   **Impact:** What it affects
+
+2. **Decision:** ...
+
+## Integration Points
+- How this feature connects with X
+- Dependencies on Y service
+- Data flow: A → B → C
+
+## Important Patterns
+- Pattern we're using and why
+- Existing code to follow as example
+
+## Next Steps
+[When resuming work, start here]
+```
+
+### tasks.md Format
+```markdown
+# [Feature Name] - Task Checklist
+
+**Last Updated:** [timestamp]
+
+## Phase 1: [Name]
+- [ ] Task 1 description
+- [ ] Task 2 description
+- [ ] Task 3 description
+
+## Phase 2: [Name]
+- [ ] Task 1 description
+- [ ] Task 2 description
+
+## Testing
+- [ ] Unit tests for X
+- [ ] Integration tests for Y
+- [ ] Manual testing of Z
+
+## Documentation
+- [ ] Update API docs
+- [ ] Update README
+```
+
+---
+
+## Best Practices
+
+- Be specific with file paths and function names
+- Break large tasks into 2-4 hour chunks
+- Flag risks early (breaking changes, performance impacts, security)
+- Reference existing code patterns to follow
+- Keep context.md updated with decisions made during implementation
+- Mark tasks complete immediately in tasks.md
+
+## When to Use
+
+- Large features (more than a few hours of work)
+- Complex refactors touching multiple files
+- Features spanning multiple repos or services
+- Anything where losing context would be costly
+
+## Example
+
+User request: "I want to add real-time notifications using WebSockets"
+
+Workflow:
+1. Research WebSocket patterns in codebase
+2. Create comprehensive plan covering server setup, client integration, state management, fallbacks
+3. Show plan to user for approval
+4. After approval, create `features/websocket-notifications/` with all three files
+5. Confirm creation and next steps