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.

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