plan

Create Plan

You are tasked with creating a detailed implementation plan based on research findings. This is Phase 2 of the Frequent Intentional Compaction (FIC) workflow.

Initial Setup:

When this command is invoked, respond with:

📋 Starting implementation planning (Phase 2 of FIC workflow)

I'll create a detailed implementation plan based on the research findings.

Please provide either:
1. The path to your research document from Phase 1, or
2. A summary of what needs to be implemented

Planning Process:

1. Context Gathering

If research document exists:

• Read the research document from Phase 1
• Extract key findings and open questions
• Identify components that need modification
• For GitHub issues: Extract reproduction steps and root cause

If starting fresh:

• Detect if input is a GitHub issue (#NNN)
• If issue: Read the issue research or fetch with gh issue view
• Otherwise: Conduct quick research using the codebase-locator agent
• Identify key files and patterns
• Understand current implementation

2. Analyze Requirements

• Clarify the desired outcome
• Identify constraints and dependencies
• Consider EdgarTools principles:
  • Simple yet powerful
  • Beginner-friendly
  • Accurate financials
  • Joyful UX with rich output

3. Design Solution

Break down the implementation into logical phases:

• Each phase should be independently testable
• Phases should build on each other
• Include verification steps for each phase
• Consider rollback strategies if needed

4. Create Detailed Plan Document

Save to: docs-internal/planning/active-tasks/YYYY-MM-DD-{topic}-plan.md

Structure:

# Implementation Plan: [Feature/Fix Name]

**Date Created**: [Current date]
**Planning Phase**: 2 of 3 (FIC Workflow)
**Based on Research**: [Link to research document if exists]
**Next Phase**: Implementation (`/implement`)

## Overview
[Brief description of what will be implemented and why]

## Current State Analysis
[Summary from research phase]
- What exists today
- Key files involved
- Current limitations

## Desired End State
[Clear description of success]
- Functional requirements
- Performance requirements
- User experience goals

## Out of Scope
[What will NOT be addressed]
- Future enhancements
- Unrelated improvements
- Items for separate tasks

## Implementation Approach

### Phase 1: [Descriptive Name] ⬜
**Goal**: [What this phase accomplishes]

**Changes**:
1. `edgar/module.py`:
   - [ ] Add method `new_functionality()`
   - [ ] Update class initialization
   ```python
   # Example of key change
   def new_functionality(self):
       # Implementation approach
       pass

1. tests/test_module.py:
   • Add test for new functionality
   • Update existing tests

Verification:

• Run: python -m pytest tests/test_module.py
• Check: New functionality works with sample data
• Verify: No regression in existing features

Phase 2: [Descriptive Name] ⬜

Goal: [What this phase accomplishes]

Changes: [Similar structure to Phase 1]

Verification: [Specific tests and checks]

Phase 3: [Integration and Polish] ⬜

Goal: Complete integration and user experience

Changes:

1. Documentation updates
2. Example scripts
3. Performance optimization
4. Rich output formatting

Verification:

• All tests pass: python -m pytest
• Documentation builds: mkdocs build
• Examples run successfully
• Performance meets requirements

Testing Strategy

Unit Tests

• New test files needed
• Existing tests to update
• Coverage requirements

Integration Tests

• End-to-end scenarios
• Edge cases to handle
• Performance benchmarks

Manual Verification

• User workflows to test
• Visual output checks (rich formatting)
• Error handling scenarios

Risk Mitigation

Potential Issues

1. Issue: [Potential problem] Mitigation: [How to handle]

2. Issue: [Another potential problem] Mitigation: [How to handle]

Rollback Plan

• How to revert changes if needed
• Backup strategies for critical data

Dependencies

• External libraries required
• Internal modules affected
• Documentation updates needed

Success Criteria

• All functional requirements met
• Tests pass with >90% coverage for new code
• Documentation complete
• No performance regression
• Clean code following EdgarTools patterns

Estimated Effort

• Phase 1: [Time estimate]
• Phase 2: [Time estimate]
• Phase 3: [Time estimate]
• Total: [Total estimate]

Notes for Implementation

• Key EdgarTools patterns to follow
• Specific gotchas to watch for
• Performance considerations
• Security considerations (API keys, rate limits)