spec-chore

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:

   gh issue create --title "chore: [Chore Name]" \
     --body "[Full specification]" \
     --label chore \
     --label maintenance
   

Template for Issue Body

## 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