gh-shavakan-claude-marketplace-commands/shavakan/docs-feature-plan.md

description

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

# [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

# [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

# [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