majiayu000 Gmacko Feature Planning
Break down feature requests into detailed implementation plans with tasks and acceptance criteria.
When to Use
- User describes a new feature to implement
- A GitHub issue needs task breakdown
- Planning sprint work
- Converting INITIAL_PLAN.md milestones into actionable tasks
Workflow
digraph feature_plan {
rankdir=TB;
node [shape=box];
start [label="Start" shape=ellipse];
gather [label="1. Gather Context"];
analyze [label="2. Analyze Requirements"];
breakdown [label="3. Break Down Tasks"];
criteria [label="4. Define Acceptance Criteria"];
estimate [label="5. Estimate Effort"];
review [label="6. Review with User"];
approved [label="Approved?" shape=diamond];
write [label="7. Write Plan Document"];
issues [label="8. Suggest Issues"];
done [label="Planning Complete" shape=ellipse];
start -> gather -> analyze -> breakdown;
breakdown -> criteria -> estimate -> review -> approved;
approved -> write [label="yes"];
approved -> analyze [label="revise"];
write -> issues -> done;
}
Execution Steps
Step 1: Gather Context
Before planning, gather necessary context:
Questions to Ask:
- What is the feature name/title?
- What problem does it solve?
- Which platforms are affected? (web/mobile/api/all)
- Is this in the INITIAL_PLAN.md? If so, which milestone?
- Any existing related code to reference?
- Any design mockups or references?
- Are there dependencies on other features?
Files to Check:
INITIAL_PLAN.md- For context on planned featuresPROJECT_MANIFEST.json- For enabled integrationspackages/db/src/schema.ts- For existing data modelpackages/api/src/routers/- For existing API patterns
Step 2: Analyze Requirements
Break down the feature into components:
## Feature Analysis
### User Stories
- As a [user type], I want [capability] so that [benefit]
### Affected Areas
- [ ] Database schema changes
- [ ] API endpoints (tRPC routers)
- [ ] Web UI components
- [ ] Mobile UI components
- [ ] Shared package updates
- [ ] Third-party integrations
### Technical Considerations
- Authentication required: yes/no
- Real-time updates needed: yes/no
- Analytics events to track: [list]
- Error states to handle: [list]
Step 3: Break Down Tasks
Create a hierarchical task breakdown:
## Task Breakdown
### 1. Database Layer
- [ ] Add/modify schema in `packages/db/src/schema.ts`
- [ ] Create migration
- [ ] Add indexes if needed
### 2. API Layer
- [ ] Create/update tRPC router in `packages/api/src/routers/`
- [ ] Add input validation (Zod schemas)
- [ ] Implement business logic
- [ ] Add error handling
### 3. Web UI
- [ ] Create page/component in `apps/web/src/`
- [ ] Connect to tRPC hooks
- [ ] Add loading/error states
- [ ] Implement responsive design
### 4. Mobile UI (if applicable)
- [ ] Create screen/component in `apps/mobile/src/`
- [ ] Connect to tRPC hooks
- [ ] Handle platform-specific UI
### 5. Integration
- [ ] Add analytics events
- [ ] Add error tracking
- [ ] Update i18n strings
### 6. Testing & QA
- [ ] Write test cases
- [ ] Manual testing checklist
- [ ] Cross-platform verification
Step 4: Define Acceptance Criteria
Write clear, testable acceptance criteria:
## Acceptance Criteria
### Functional
- [ ] User can [action 1]
- [ ] System displays [expected behavior]
- [ ] Data is persisted correctly
- [ ] Errors are handled gracefully
### Non-Functional
- [ ] Page loads in < 2 seconds
- [ ] Works on mobile viewports
- [ ] Accessible (keyboard navigation, screen readers)
- [ ] No console errors
### Edge Cases
- [ ] Empty state handled
- [ ] Maximum limits respected
- [ ] Concurrent access handled
Step 5: Estimate Effort
Provide rough estimates:
| Task | Estimate | Complexity |
|---|---|---|
| Database changes | 1h | Low |
| API implementation | 2h | Medium |
| Web UI | 4h | Medium |
| Mobile UI | 3h | Medium |
| Testing | 2h | Low |
| Total | 12h | - |
Step 6: Review with User
Present the plan summary:
Feature Plan: [Feature Name]
Summary: [One sentence description]
Scope:
- Platforms: [Web/Mobile/Both]
- Dependencies: [None/List]
- Estimated effort: [X hours]
Tasks: [X] tasks across [Y] areas
Does this look complete? Should I adjust anything?
Step 7: Write Plan Document
Write to docs/ai/handoffs/{feature-id}-plan.md:
# Feature Plan: [Feature Name]
> Generated on [date]
> Author: AI Assistant
## Overview
**Feature**: [Name]
**Issue**: #[number] (if exists)
**Milestone**: [From INITIAL_PLAN.md]
**Estimated Effort**: [X hours]
## Problem Statement
[What problem this solves]
## User Stories
- As a [user], I want [goal] so that [benefit]
## Technical Design
### Data Model Changes
```typescript
// New/modified schema
API Changes
// New/modified procedures
UI Components
- Web: [List of components]
- Mobile: [List of screens] (if applicable)
Task Breakdown
[Detailed task list from Step 3]
Acceptance Criteria
[Criteria from Step 4]
Test Plan
Manual Testing
- [Test case 1]
- [Test case 2]
Automated Testing
- Unit tests for [component]
- Integration tests for [API]
Dependencies
- Requires: [Other features/issues]
- Blocks: [Dependent features]
Rollback Plan
If issues arise:
- [Rollback step 1]
- [Rollback step 2]
Open Questions
- [Question 1]
- [Question 2]
### Step 8: Suggest Issues
Recommend GitHub issue creation:
> Based on this plan, I recommend creating these issues:
>
> 1. **[Feature]: [Main feature name]** - Epic/parent issue
> 2. **[Task]: Database schema for [feature]** - Subtask
> 3. **[Task]: API endpoints for [feature]** - Subtask
> 4. **[Task]: Web UI for [feature]** - Subtask
>
> Would you like me to create these issues using `gmacko-dev-issue-create`?
## Output Artifacts
- `docs/ai/handoffs/{feature-id}-plan.md` - Detailed plan
- Suggested GitHub issues (optional)
## Red Flags
| Rationalization | Correction |
|-----------------|------------|
| "This is simple, no need for a plan" | ALL features get plans; even small ones |
| "I'll skip acceptance criteria" | Criteria are required for QA handoff |
| "User knows what they want, no questions needed" | ALWAYS gather context first |
| "Estimates don't matter" | Estimates help prioritization |
## Integration Points
- **Input**: Feature request (verbal or issue)
- **References**: `INITIAL_PLAN.md`, `PROJECT_MANIFEST.json`
- **Output**: `docs/ai/handoffs/{id}-plan.md`
- **Next**: `gmacko-dev-issue-create` or direct implementation