# Weekly useEffect Review Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. **Goal:** Add a weekly Copilot audit that finds incorrect React Effects and opens at most five independent draft pull requests with verified fixes. **Architecture:** gh-aw compiles one Markdown workflow into the GitHub Actions lock file it executes. The agent job receives read-only repository access, Copilot request permission, and the pinned Bun runtime; the separate safe-output job is the only job that can create draft PRs, subject to a five-PR cap and blocked protected files. **Tech Stack:** GitHub Agentic Workflows (`gh-aw`), GitHub Actions, GitHub Copilot, Bun 1.3.2. --- ## File structure - Create: `.github/workflows/weekly-use-effect-review.md` — authored gh-aw instructions and restrictive frontmatter. - Create: `.github/workflows/weekly-use-effect-review.lock.yml` — compiler-generated GitHub Actions workflow; never edit manually. - Create/modify: `.gitattributes`, `.github/agents/agentic-workflows.agent.md`, `.vscode/settings.json` — generated by `gh aw init`; they register repository-level gh-aw support without Copilot MCP files. - Modify: `docs/superpowers/plans/2026-08-19-weekly-use-effect-review.md` — mark completed implementation steps during execution. ### Task 1: Authenticate and initialize gh-aw support **Files:** - Create/modify: `.gitattributes` - Create: `.github/agents/agentic-workflows.agent.md` - Create/modify: `.vscode/settings.json` - [x] **Step 1: Restore GitHub CLI authentication with the repository and workflow scopes** Run: ```bash gh auth login -h github.com --scopes repo,workflow gh auth status ``` Expected: `gh auth status` reports the intended GitHub account as logged in; do not proceed while it reports an invalid token. - [x] **Step 2: Initialize gh-aw without Copilot-only MCP configuration** Run: ```bash gh aw init --engine codex --no-mcp git diff -- .gitattributes .github/agents/agentic-workflows.agent.md .vscode/settings.json ``` Expected: the initializer marks `.lock.yml` files as generated and creates the generic repository support files. Copilot request authentication is configured in the workflow itself, not through a repository secret. - [x] **Step 3: Commit the generated gh-aw setup** Run: ```bash git add .gitattributes .github/agents/agentic-workflows.agent.md .vscode/settings.json git commit -m "Initialize agentic workflows for Codex" ``` Expected: one focused commit containing only initializer output. If the initializer did not change one of the listed files, omit that path from `git add` rather than creating it by hand. ### Task 2: Author the weekly Effect audit **Files:** - Create: `.github/workflows/weekly-use-effect-review.md` - [x] **Step 1: Create the workflow source with the exact frontmatter and audit instructions** Create `.github/workflows/weekly-use-effect-review.md` with: ```markdown --- on: schedule: - cron: "30 9 * * 3" timezone: Europe/London workflow_dispatch: permissions: contents: read copilot-requests: write runtimes: bun: version: "1.3.2" steps: - name: Install repository dependencies run: bun install --frozen-lockfile engine: copilot safe-outputs: create-pull-request: title-prefix: "[use-effect] " draft: true max: 5 fallback-as-issue: false protected-files: blocked excluded-files: - bun.lock allowed-branches: - "automation/use-effect/*" --- # Weekly React Effect review Review the entire repository for incorrect React Effects. Inspect `useEffect`, `useLayoutEffect`, `useInsertionEffect`, and custom hooks that behave like an Effect. Treat each Effect as a synchronization boundary. For every Effect, identify its component or hook and source location. Ask which external system it synchronizes with. Valid external systems include browser or DOM APIs, network requests, timers, subscriptions, storage, third-party widgets, analytics, and non-React stores. Classify the intent as `derive-render`, `handle-event`, `reset-or-adjust-state`, `external-sync`, `data-fetch`, or `escape-hatch`. - Replace derived state with render-time derivation; use `useMemo` only for an expensive pure computation or an identity contract. - Move interaction-driven work into the event handler or command that caused it. - Prefer a `key` for whole-subtree resets and a clearer state shape for partial adjustment. - Prefer `useSyncExternalStore` for external stores. - For data fetching kept in an Effect, handle cancellation or stale responses. - For a genuine external synchronization Effect, keep it only when dependencies include every reactive value read by setup or cleanup, cleanup mirrors setup, it tolerates Strict Mode, and it has no dependency suppression. Only fix high-confidence violations. Each pull request must contain exactly one independent violation, start from the default branch, and use a branch named `automation/use-effect/`. Do not stack or combine pull requests. Stop after five pull requests; leave remaining findings for a later run. Do not change dependency manifests, lockfiles, workflow files, agent instructions, or other protected files. Do not create an issue or pull request when a finding is uncertain, a focused verification cannot be identified, or the verification fails. Before proposing each fix, run the narrowest relevant check. Use `bun test` for logic covered by unit tests, `bun run types` for TypeScript changes, `bun run ci` for formatting and lint-sensitive changes, and `bun run e2e` only when the changed Effect alters browser behavior that cannot be covered without a browser. In each draft PR, explain the Effect's location and classification, why the old Effect was incorrect, the selected refactor, and the verification command and result. ``` - [x] **Step 2: Validate the authored workflow before generating Actions YAML** Run: ```bash gh aw validate weekly-use-effect-review ``` Expected: validation exits successfully with no schema, action-pinning, or safe-output-policy errors. - [x] **Step 3: Compile the lock file and inspect the generated safeguards** Run: ```bash gh aw compile weekly-use-effect-review --validate --approve git diff -- .github/workflows/weekly-use-effect-review.md .github/workflows/weekly-use-effect-review.lock.yml ``` Expected: the compiler creates `weekly-use-effect-review.lock.yml`. Confirm it has the Wednesday 09:30 London schedule, manual dispatch, Copilot authentication, and a separate safe-output job that limits draft PR creation to five and blocks protected files. - [x] **Step 4: Commit the source and generated lock file together** Run: ```bash git add .github/workflows/weekly-use-effect-review.md .github/workflows/weekly-use-effect-review.lock.yml git commit -m "Add weekly useEffect review workflow" ``` Expected: source and lock file are committed in the same change; no manual edits are made to the lock file. ### Task 3: Configure credentials and perform the first guarded run **Files:** - Verify externally: GitHub Copilot requests are enabled and centrally billed for `githubnext/chopin` - Verify externally: the repository Actions workflow and any created draft pull requests - [ ] **Step 1: Confirm GitHub Copilot request access** Run: Confirm in the GitHub organization settings that GitHub Copilot requests are enabled and centrally billed for this repository. No repository secret is required; the workflow requests the short-lived `copilot-requests: write` permission. Expected: the organization permits the workflow's Copilot requests. If access is not enabled, the first manual run fails before the agent starts and no pull request is created. - [ ] **Step 2: Push the committed workflow configuration through a pull request** Run: ```bash git switch -c maggie/weekly-use-effect-review git push -u origin maggie/weekly-use-effect-review gh pr create --base main --head maggie/weekly-use-effect-review \ --title "Add weekly useEffect review workflow" \ --body "Adds a Wednesday 09:30 Europe/London Copilot workflow that audits React Effects and creates up to five guarded draft PRs per run.\n\nSecurity review: adds `copilot-requests: write`; no repository secret or API key is introduced." ``` Expected: the pull request contains the initializer and workflow commits. Merging it to the default branch enables the schedule. - [ ] **Step 3: Trigger and observe the first live run** Run: ```bash gh aw run weekly-use-effect-review gh aw status gh aw logs weekly-use-effect-review ``` Expected: the workflow runs with GitHub Copilot. It either completes with no changes or creates no more than five independent draft PRs. Each created PR states the finding and verification result; protected-file changes and failed checks produce no PR. - [ ] **Step 4: Commit the completed plan checklist** Run: ```bash git add docs/superpowers/plans/2026-08-19-weekly-use-effect-review.md git commit -m "Record weekly useEffect workflow rollout" ``` Expected: the plan records what was performed and what the first run produced, without secrets or generated run logs.