opensite-ai/opensite-skills / large-scale-refactor
large-scale-refactor
UnverifiedGuardrails, 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.
| File | Kind | Size |
|---|---|---|
| CONTRIBUTING.md | markdown | 1.5 KB |
| README.md | markdown | 7.7 KB |
| SKILL.md | skill md | 17.9 KB |
| agents/openai.yaml | config | 5.4 KB |
| examples/complete-workflow.md | markdown | 9.8 KB |
| examples/refactor-spec.md | markdown | 2.2 KB |
| references/activation.md | markdown | 4.9 KB |
| scripts/generate_allowlist.pyexecutable | script | 8.9 KB |
| scripts/test_verify_scope.py | script | 7.8 KB |
| scripts/verify_scope.pyexecutable | script | 7.6 KB |
| templates/change-manifest.md | markdown | 1.6 KB |
| templates/observations.md | markdown | 2.9 KB |
| templates/refactor-scope-allowlist.example | other | 5.5 KB |
| templates/session-handoff.md | markdown | 6.1 KB |
templates/observations.md
View on GitHub# OBSERVATIONS.md — Out-of-Scope Findings Log
> **Purpose**: This file captures everything the agent noticed but did not act on.
> Log here. Never act on entries here. A human reviews this file at the end of the task.
>
> **Rule**: If you are tempted to fix, improve, or investigate something that is not
> in the approved spec — write it here and move on. The task has one job.
---
## Observations (NOT acted upon — logged for human review)
| # | File | Observation | Type | Severity | Logged at |
|---|------|-------------|------|----------|-----------|
| 1 | `src/api/user.ts` | Possible N+1 query in `fetchUsers` — each user triggers a separate `getRoles()` call | Performance | Medium | Subtask 2, file 18 |
| 2 | `src/components/Button.tsx` | Inline styles could use CSS custom properties from the design token system | Style | Low | Subtask 1, file 4 |
| 3 | `src/utils/format.ts` | `formatCurrency` does not handle negative values — returns `"$-12.00"` instead of `"-$12.00"` | Bug | High | Subtask 1, file 7 |
---
## Observation Entry Format
Copy this block to add a new observation:
```
| [N] | `path/to/file.ext` | [What you noticed — be specific] | [Bug / Performance / Style / Security / Architecture / Dependency] | [Critical / High / Medium / Low] | [Subtask N, file N] |
```
---
## Severity Guide
| Severity | Meaning | Example |
|----------|---------|---------|
| **Critical** | Active data loss, security hole, or system-breaking defect | SQL injection, auth bypass, data corruption |
| **High** | Incorrect behaviour affecting users or correctness | Wrong calculation result, silent error swallowed |
| **Medium** | Degraded performance or maintainability risk | N+1 query, unbounded loop, dead code |
| **Low** | Style inconsistency, minor improvement opportunity | Unused import, stale comment, formatting |
---
## Type Guide
| Type | Meaning |
|------|---------|
| **Bug** | Code that produces incorrect output or has unhandled error paths |
| **Performance** | Inefficient query, algorithm, or rendering pattern |
| **Security** | Potential vulnerability, exposed credential, insufficient validation |
| **Architecture** | Structural concern — coupling, abstraction boundary, module design |
| **Dependency** | Package that is outdated, unused, or could be replaced |
| **Style** | Inconsistency with the project's established conventions |
| **Debt** | Known workaround, TODO, or deferred decision that accumulates risk |
---
## What Happens to This File
1. The agent commits `OBSERVATIONS.md` with each session's changes.
2. At the end of the full task, a human reviews this file and triages entries.
3. **Critical / High** entries are typically filed as separate issues or PRs.
4. **Medium / Low** entries are batched for a future cleanup pass.
5. Nothing in this file is acted on during the current refactor task.
---
## Notes
<!-- Add any free-form notes the human should read alongside the table above. -->Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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 implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |