systematic-feature-builder

# Systematic Feature Builder Implement features systematically with detailed planning, progress tracking, and comprehensive testing. ## When to Use This Skill Use this skill when: - Building new features from requirements or specifications - Adding functionality to existing projects - Implementing multi-step features that require coordination - User requests "systematic", "organized", or "methodical" approach - User provides a spec or detailed requirements document - Features require database changes, API integration, or complex logic ## Core Workflow Follow these five phases in order: 1. **Requirements Analysis** - Understand what needs to be built 2. **Implementation Planning** - Create detailed, step-by-step plan 3. **Systematic Implementation** - Execute plan with progress tracking 4. **Testing & Verification** - Validate at multiple levels 5. **Documentation & Checkpoint** - Create comprehensive checkpoint ## Phase 1: Requirements Analysis ### Gather Information Extract clear requirements from user input: - What features need to be built? - What is the expected behavior? - Are there existing examples or references? - What are the success criteria? ### Identify Dependencies Determine what exists and what needs to be created: - Existing code/components that can be reused - Database schema changes required - External services or APIs needed - Dependencies between features ### Clarify Ambiguities Ask targeted questions if requirements are unclear: - Edge cases and error handling - User permissions and access control - Performance or scalability requirements - UI/UX preferences ## Phase 2: Implementation Planning ### Create Detailed Plan Use the implementation plan template: ```bash # Copy template to project cp /home/ubuntu/skills/systematic-feature-builder/templates/implementation-plan-template.md \ <project-path>/docs/plans/YYYY-MM-DD-feature-name.md ``` **Plan Structure:** - Overview and objectives - Task breakdown with estimated time - Step-by-step instructions with file paths - Testing strategy for each task - Success criteria - Rollback plan ### Break Down Into Atomic Tasks Each task should: - Be completable in one sitting (30-90 minutes) - Have clear inputs and outputs - Be independently testable - Have explicit success criteria **Example Task Breakdown:** ```markdown ### Task 1: Add Database Field (15 min) 1. Update schema.ts with new field 2. Run `pnpm db:push` to migrate 3. Verify field exists in database ### Task 2: Create Backend Endpoint (30 min) 1. Add endpoint to router 2. Implement business logic 3. Add input validation 4. Write unit tests ### Task 3: Build Frontend Component (45 min) 1. Create component file 2. Add tRPC integration 3. Implement UI with shadcn/ui 4. Handle loading/error states ``` ### Update todo.md Add all planned tasks to project's todo.md: ```markdown ## [Feature Name] - [ ] Task 1: Database changes - [ ] Task 2: Backend endpoint - [ ] Task 3: Frontend component - [ ] Task 4: Testing - [ ] Task 5: Documentation ``` ## Phase 3: Systematic Implementation ### Execute Plan Sequentially Implement tasks in order, following the plan: 1. **Start with backend/data layer** (database, APIs) 2. **Then business logic** (endpoints, services) 3. **Finally UI layer** (components, pages) This order minimizes rework and allows incremental testing. ### Track Progress in todo.md Mark tasks complete as you finish them: ```markdown ## [Feature Name] - [x] Task 1: Database changes - [x] Task 2: Backend endpoint - [ ] Task 3: Frontend component ← Currently working on this - [ ] Task 4: Testing - [ ] Task 5: Documentation ``` Use `file` tool's `edit` action to update checkboxes efficiently. ### Handle Deviations If you deviate from the plan: - Document why in the plan file - Update todo.md with new tasks - Adjust time estimates if needed ### Communicate Progress For long implementations, send `info` messages at milestones: - "✅ Task 1 complete: Database schema updated" - "📊 Progress: 3/5 tasks complete" - "⚠️ Encountered issue with X, implementing alternative approach" ## Phase 4: Testing & Verification ### Three-Level Testing Test at all three levels before checkpoint: **1. Unit Tests** - Individual functions and endpoints - Database operations - Input validation **2. Integration Tests** - Features working together - End-to-end workflows - External service integration **3. Manual Verification** - UI renders correctly - User flows work as expected - Edge cases handled gracefully ### Webdev-Specific Testing For webdev projects: ```bash # Run automated tests pnpm test # Check dev server health # (use webdev_check_status tool) # Manual browser testing # - Open dev server URL # - Test feature in browser # - Check console for errors # - Verify responsive design ``` Refer to `references/testing-strategies.md` for detailed testing approaches. ### Verify Completion Before creating checkpoint, verify all tasks complete: ```bash python /home/ubuntu/skills/systematic-feature-builder/scripts/verify_completion.py \ <project-path>/todo.md ``` This script checks for incomplete `[ ]` items and reports them. ## Phase 5: Documentation & Checkpoint ### Update Documentation Ensure documentation reflects changes: - Update README if user-facing features added - Add inline code comments for complex logic - Update API documentation if endpoints changed ### Create Comprehensive Checkpoint Follow checkpoint guidelines in `references/checkpoint-guidelines.md`. **Checkpoint Description Template:** ```markdown [Feature name]: [brief summary] ## Features Added ### 1. [Feature Name] - Key capability 1 - Key capability 2 - Location/integration point ## Technical Details **Database Changes:** - [Schema changes] **New Files:** - [Important new files and their purpose] **Dependencies:** - [New packages added] ## Testing - [X] tests passing - [Y] tests failing (if any, explain why) ## Next Steps - [Suggested follow-up actions] ``` ### Webdev Checkpoint Checklist Before creating webdev checkpoint: - [ ] All tests passing (or failures documented) - [ ] `webdev_check_status` shows no critical errors - [ ] Feature works in dev server - [ ] todo.md updated with completed items marked `[x]` - [ ] Large media files uploaded to S3 (not in project directory) - [ ] Database migrations applied successfully ## Webdev-Specific Guidance ### Database Changes Always follow this sequence: 1. Edit `drizzle/schema.ts` 2. Run `pnpm db:push` to apply migration 3. Verify migration succeeded 4. Test database operations ### File Organization Create files in this order: 1. **Database layer**: `drizzle/schema.ts` 2. **Data access**: `server/db.ts` (query helpers) 3. **Business logic**: `server/*-router.ts` (tRPC endpoints) 4. **Frontend**: `client/src/components/*.tsx`, `client/src/pages/*.tsx` ### Testing Pattern ```typescript // server/feature.test.ts import { describe, it, expect } from 'vitest'; describe('Feature Tests', () => { it('should handle valid input', async () => { // Arrange const input = { /* test data */ }; // Act const result = await endpoint(input); // Assert expect(result).toMatchObject({ expected }); }); it('should handle error cases', async () => { // Test error scenarios }); }); ``` ### Common Patterns **Adding a Feature:** 1. Plan → Update todo.md 2. Schema → Database migration 3. Backend → tRPC endpoint + tests 4. Frontend → Component + integration 5. Test → Manual verification 6. Checkpoint → Comprehensive description **Fixing a Bug:** 1. Reproduce → Document steps 2. Identify → Root cause analysis 3. Fix → Minimal change 4. Test → Verify fix + no regressions 5. Checkpoint → Explain bug and fix ## Best Practices ### Do ✅ **Write plans before coding** - Saves time, reduces rework ✅ **Update todo.md actively** - Provides clear progress tracking ✅ **Test incrementally** - Catch issues early ✅ **Document decisions** - Future you will thank present you ✅ **Create detailed checkpoints** - Enable easy rollback and review ### Don't ❌ **Skip planning** - Leads to disorganized implementation ❌ **Implement everything at once** - Hard to debug, test, and review ❌ **Forget to update todo.md** - Loses track of progress ❌ **Skip testing** - Bugs slip into production ❌ **Create vague checkpoints** - Useless for rollback or review ## Templates and Scripts ### Available Resources **Templates** (`templates/`): - `implementation-plan-template.md` - Structured feature plan - `todo-template.md` - Format for tracking features **Scripts** (`scripts/`): - `verify_completion.py` - Validates all checklist items complete **References** (`references/`): - `testing-strategies.md` - Testing approaches by project type - `checkpoint-guidelines.md` - Checkpoint best practices ### Using Templates Copy templates to your project: ```bash # Implementation plan cp /home/ubuntu/skills/systematic-feature-builder/templates/implementation-plan-template.md \ <project>/docs/plans/$(date +%Y-%m-%d)-feature-name.md # Todo file (if project doesn't have one) cp /home/ubuntu/skills/systematic-feature-builder/templates/todo-template.md \ <project>/todo.md ``` ## Examples ### Example: Adding Bulk CSV Import Feature **Phase 1: Requirements** - Admin needs to import rep codes from CSV - CSV format: email, repCode - Show import results with errors **Phase 2: Plan** ```markdown ### Task 1: Backend Endpoint (30 min) 1. Add bulkImportRepCodes to admin-router.ts 2. Parse CSV data from input 3. Validate each row 4. Update database 5. Return results with errors ### Task 2: Frontend Component (45 min) 1. Create BulkRepCodeImport.tsx 2. Add file upload input 3. Integrate Papa Parse 4. Show import results 5. Add CSV template download ### Task 3: Integration (15 min) 1. Add component to Admin page 2. Test with sample CSV 3. Verify error handling ``` **Phase 3: Implementation** - Implement tasks sequentially - Update todo.md after each task - Test each component independently **Phase 4: Testing** - Unit test: endpoint validates CSV correctly - Integration test: upload CSV via UI - Manual test: download template, upload, verify results **Phase 5: Checkpoint** ``` Title: Add bulk rep code CSV import ## Features Added - Admin endpoint for bulk importing rep codes - BulkRepCodeImport component with file upload - Papa Parse integration - Detailed error reporting ## Technical Details **New Files:** - server/admin-router.ts: bulkImportRepCodes endpoint - client/src/components/BulkRepCodeImport.tsx **Dependencies:** - papaparse, @types/papaparse ## Testing - 52 tests passing ``` ## Troubleshooting **"Plan is too detailed/taking too long"** → Reduce granularity. Focus on major steps, not every line of code. **"Implementation deviating from plan"** → Update plan document with deviations and reasoning. Adjust todo.md. **"Tests failing after implementation"** → Fix tests before checkpoint. Document any intentional test changes. **"Checkpoint description too long"** → Focus on what changed and why. Move detailed technical notes to plan document. ## Summary This skill provides a systematic, organized approach to feature implementation: 1. **Analyze** requirements thoroughly 2. **Plan** implementation with detailed steps 3. **Implement** systematically with progress tracking 4. **Test** at multiple levels 5. **Document** comprehensively in checkpoint The result: high-quality, well-tested features with clear documentation and easy rollback capability.