# Spec a Chore
You are about to create a chore specification and turn it into a GitHub issue ready for implementation.
## Process
1. **Gather Requirements**
- Ask the user for the chore name and description if not provided
- Understand the maintenance goal and technical debt being addressed
- Identify scope, constraints, and potential impacts
2. **Write Chore Specification**
Create a comprehensive specification including:
- **Chore** name and description
- **Current State** (what's wrong/needs improvement)
- **Desired State** (what success looks like)
- **Implementation Steps** (clear, actionable tasks)
- **Acceptance Criteria**
- **Out of Scope** (what this chore won't address)
- **Impact Analysis** (what might be affected)
- **Technical Details**
3. **Format as GitHub Issue**
Structure the issue with:
- Clear title: `chore: [Chore Name]`
- Labels: `chore`, `maintenance`, `technical-debt` (as appropriate)
- Milestone (if applicable)
- Complete specification in the body
- Testing/validation requirements
4. **Create the Issue**
Use the `gh` CLI to create the issue:
```bash
gh issue create --title "chore: [Chore Name]" \
--body "[Full specification]" \
--label chore \
--label maintenance
```
## Template for Issue Body
```markdown
## Chore: [Chore Name]
### Motivation
[Explain why this chore is needed - technical debt, maintenance, performance, etc.]
### Current State
[Describe the current situation that needs improvement]
- Problem 1: [specific issue]
- Problem 2: [specific issue]
- Technical debt: [if applicable]
### Desired State
[Describe what the codebase should look like after this chore]
- Improvement 1: [specific outcome]
- Improvement 2: [specific outcome]
- Resolved debt: [if applicable]
### Implementation Steps
1. **Step 1**: [Clear action]
- Sub-task 1.1
- Sub-task 1.2
2. **Step 2**: [Clear action]
- Sub-task 2.1
- Sub-task 2.2
3. **Step 3**: [Clear action]
- Sub-task 3.1
- Sub-task 3.2
### Acceptance Criteria
- [ ] All deprecated dependencies updated
- [ ] All obsolete code removed
- [ ] Documentation updated to reflect changes
- [ ] No functionality broken (all tests pass)
- [ ] Performance metrics maintained or improved
- [ ] Code quality metrics improved
### Out of Scope
- This chore will NOT [explicitly excluded work]
- Future improvements: [related but deferred work]
### Impact Analysis
#### Systems Affected
- Component A: [impact description]
- Component B: [impact description]
#### Risk Assessment
- **Low Risk**: [areas with minimal impact]
- **Medium Risk**: [areas needing careful testing]
- **High Risk**: [critical areas requiring extra attention]
### Technical Details
#### Dependencies to Update
- Package A: from version X to Y
- Package B: from version X to Y
#### Files to Modify
- `path/to/file1.ts`: [change description]
- `path/to/file2.ts`: [change description]
#### Configuration Changes
- Config A: [change description]
- Config B: [change description]
### Validation Requirements
- [ ] All existing tests pass
- [ ] Build succeeds without warnings
- [ ] Linting passes without errors
- [ ] Performance benchmarks show no regression
- [ ] Manual testing of affected areas
- [ ] Security scan shows no new vulnerabilities
### Rollback Plan
If issues are discovered:
1. [Step to revert changes]
2. [Step to restore previous state]
3. [Verification steps]
### Definition of Done
- [ ] All acceptance criteria met
- [ ] Code changes reviewed and approved
- [ ] Documentation updated where necessary
- [ ] No increase in technical debt
- [ ] Changeset added (if applicable)
- [ ] CI/CD pipeline passes
```
## Important Notes
1. **Be Specific**: Define clear, measurable improvements
2. **Focus on Value**: Explain WHY this maintenance is important
3. **Minimize Risk**: Include thorough impact analysis
4. **Keep it Atomic**: One chore should address one concern
5. **Make it Trackable**: Provide clear steps and criteria
## Common Chore Types
### Dependency Updates
```markdown
## Chore: Update Node.js to v22 LTS
### Motivation
Node.js 20 is approaching end-of-life. Updating to v22 LTS ensures continued security updates and access to performance improvements.
### Current State
- Running Node.js 20.x
- Missing performance improvements from v22
- Security patches will end in [date]
```
### Code Refactoring
```markdown
## Chore: Refactor authentication module to use dependency injection
### Motivation
Current authentication module has tight coupling making it difficult to test and maintain. Refactoring to use DI will improve testability and maintainability.
### Current State
- Direct instantiation of dependencies
- Difficult to mock for testing
- Hard to swap implementations
```
### Technical Debt Reduction
```markdown
## Chore: Remove deprecated API endpoints
### Motivation
Legacy API endpoints marked for deprecation 6 months ago are still present, adding maintenance burden and confusion.
### Current State
- 5 deprecated endpoints still active
- Duplicate code paths
- Increased maintenance overhead
```
### Build/CI Improvements
```markdown
## Chore: Optimize CI pipeline for faster feedback
### Motivation
Current CI pipeline takes 15+ minutes, slowing down development feedback loop.
### Current State
- Serial test execution
- No caching of dependencies
- Redundant build steps
```
## Example Output
After gathering requirements, create an issue like:
```bash
gh issue create --title "chore: migrate from jest to vitest" \
--body "## Chore: Migrate from Jest to Vitest
### Motivation
Jest has become slow for our test suite (5+ minutes). Vitest offers 3-5x faster test execution and better TypeScript support.
### Current State
- Test suite takes 5+ minutes to run
- Jest configuration is complex
- Type checking requires separate step
### Desired State
- Test suite runs in under 2 minutes
- Simplified test configuration
- Integrated type checking
[... full specification ...]" \
--label chore \
--label maintenance \
--label testing
```
The created issue will be ready for implementation using the `/implement-github-issue` command.
