Feature Implementation Pattern

This skill defines the standard workflow for implementing features from your project's requirements or implementation plan.

Implementation Workflow

1. Read Requirements

• •Locate the feature/requirement in your project documentation
• •Understand the requirements, acceptance criteria, and test coverage expectations
• •Identify files to create/modify
• •Note any specification references

2. Create TODO List

Use todo_write tool to track implementation tasks:

todo_write(merge=False, todos=[
    {'id': 'feature_implementation', 'content': 'Implement feature X', 'status': 'in_progress'},
    {'id': 'feature_tests', 'content': 'Write tests for feature X', 'status': 'pending'},
    {'id': 'feature_docs', 'content': 'Update documentation', 'status': 'pending'}
])

3. Implement Code

• •Create/modify source files as specified
• •Follow project conventions (type hints, docstrings, error codes)
• •Use established patterns and models
• •Implement error handling with custom error codes
• •Add necessary imports

4. Write Tests

Follow the test-writing pattern:

• •Write incremental tests first (for development)
• •Then verify acceptance criteria
• •Use descriptive test names
• •Add type annotations: -> None
• •Test both success and error cases

5. Run Quality Checks

Before marking complete:

• •Run linters: ruff and black
• •Run type checker: mypy --strict --explicit-package-bases src/
• •Run tests: pytest tests/ -v
• •Ensure all tests pass before proceeding
• •Fix any issues

6. Update Documentation

Update project documentation:

• •Mark feature as complete in relevant docs
• •Add Implementation Notes section with key details
• •Update test coverage documentation
• •Update acceptance criteria status
• •Update any API or user documentation

7. Commit and Push

Only commit after all tests pass and quality checks succeed.

Follow commit format conventions:

feat(<scope>): Implement <feature name>

- [List of key implementations]
- [Key features added]

Tests:
- [List of tests added]

Files:
- [List of files changed with descriptions]

Important: Only commit after:

• •✅ All tests pass (pytest tests/ -v)
• •✅ Linters pass (ruff and black)
• •✅ Type checker passes (mypy)
• •✅ Documentation updated
• •✅ Feature verified to work correctly

After committing, push to GitHub automatically.

Feature Types

Core Business Logic

• •Implement domain models and business rules
• •Add validators for data integrity
• •Write comprehensive unit tests
• •Target: 100% coverage on core logic

Service Layer

• •Implement service logic
• •Write comprehensive unit tests
• •Test all edge cases and error scenarios
• •Target: ≥90% coverage on services

API Endpoints

• •Follow API endpoint implementation patterns
• •Create REST routes
• •Write integration tests with test client
• •Verify acceptance criteria

UI Components

• •Implement user interface components
• •Write component tests
• •Test user interactions and state management
• •Verify accessibility and responsiveness

Common Patterns

Error Handling

• •Use consistent error codes
• •Return appropriate result wrappers with error codes
• •Return HTTP status codes for API endpoints
• •Follow error handling patterns

Test Organization

• •Unit tests: tests/unit/<module>/test_<component>.py
• •Integration tests: tests/integration/test_<feature>.py
• •API tests: tests/integration/api/test_<endpoint>.py

File Structure

• •Source files: Follow project structure conventions
• •Test files mirror source structure
• •Follow naming conventions (snake_case for Python)

Best Practices

1. •Read implementation plan: Always read docs/implementation-plan.md first to understand requirements, acceptance criteria, and test specifications
2. •Track internally: Use TODO list for internal progress tracking (this is your internal mechanism, not part of the spec)
3. •Test-driven: Write tests as specified in the implementation plan - tests are called out in the plan with specific acceptance criteria
4. •One at a time: Only implement one section/sub-phase at a time. Wait for explicit user command before proceeding to the next section/sub-phase.
5. •Verify AC: Ensure all acceptance criteria from the plan are met
6. •Update plan: Mark features complete in docs/implementation-plan.md immediately after implementation
7. •Commit frequently: Commit after each completed sub-phase, then push to GitHub

Edge Cases

When Implementation Differs from Plan

• •Update the plan to reflect actual implementation
• •Document deviations in Implementation Notes
• •Ensure acceptance criteria are still met

When Tests Reveal Issues

• •Fix issues in code before marking complete
• •Update plan if requirements change
• •Document lessons learned

When Multiple Files Need Updates

• •Group related changes in single commit
• •Use detailed commit message with file list
• •Ensure all tests pass before committing