Skip to content

opensite-ai/opensite-skills / large-scale-refactor

large-scale-refactor

Unverified

Guardrails, protocols, and operating constraints for large-scale, long-running, or parallelized AI coding tasks — migrations, codebase-wide refactors, framework upgrades, and any task touching 50+ files. Prevents scope creep, context drift, silent compounding errors, and emergent behavior outside the defined task boundary. Use when refactoring across files, migrating frameworks, upgrading dependencies, replacing or renaming patterns throughout a codebase, or any task touching 50+ files.

examples/refactor-spec.md

View on GitHub
# Example Refactoring Spec: JavaScript to TypeScript Migration

```
TASK SPEC
=========
**Task Name**: js-to-ts-migration
**Date**: 2024-11-15
**Initiator**: Jordan Hudgens

### What This Task Does
Convert all JavaScript files in the src/ directory to TypeScript, adding explicit type annotations while preserving all existing functionality. No logic changes, no style changes, and no dependency additions beyond @types/* packages required for type safety.

### Explicit Scope Boundary
**IN SCOPE** (agent may touch):
- [x] File types: *.js files in src/components/, src/hooks/, src/utils/
- [x] Operations: Add TypeScript type annotations, change file extensions from .js to .ts/.tsx
- [x] Directories: src/components/, src/hooks/, src/utils/
- [x] Test files: Convert corresponding *.test.js files to *.test.ts

**OUT OF SCOPE — DO NOT TOUCH** (agent must not modify):
- [ ] CSS/styling systems, color tokens, theme configuration
- [ ] Business logic, algorithms, or data transformation behavior
- [ ] Component structure beyond what is required by the task
- [ ] package.json dependencies (beyond @types/* for TS migrations)
- [ ] Build configs (webpack, babel, etc.)
- [ ] CI/CD files, deployment configs
- [ ] Files in: node_modules/, config/, scripts/, public/
- [ ] Any file not explicitly listed in IN SCOPE above

### Task Decomposition
1. Subtask A — Convert src/components/common/ — affects 15 files
2. Subtask B — Convert src/components/features/ — affects 22 files  
3. Subtask C — Convert src/hooks/ — affects 8 files
4. Subtask D — Convert src/utils/ — affects 12 files
5. Subtask E — Convert test files — affects 35 files

### Acceptance Criteria
- [ ] All .js files in scope converted to .ts/.tsx
- [ ] All files have explicit TypeScript type annotations
- [ ] All tests pass (or failures are pre-existing and documented)
- [ ] No net-new dependencies introduced (beyond spec-allowed @types/*)
- [ ] No files outside the scope boundary were modified
- [ ] Each subtask produced a separate, reviewable commit

### Rollback Plan
- Feature branch: refactor/js-to-ts-migration
- Git revert strategy: Revert individual subtask commits if needed
- Full rollback: git checkout main && git branch -D refactor/js-to-ts-migration
```
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall