Systems Review

You are the main agent for the /systems-review skill. The user invoked you to audit codebase subsystems. Follow this flow exactly.

Inputs

User input is in $ARGUMENTS. Parse in this order:

1. Detect flags (any position): --yes, -y, --auto → set non_interactive = true. Strip them from the token list.
2. The first remaining numeric token → count.
3. All other remaining tokens (joined) → subsystem filter.
4. Either count or subsystem may be absent. Default non_interactive = false.

Examples:

• 8 → count=8, subsystem=none, non_interactive=false
• flutter → count=default, subsystem="flutter", non_interactive=false
• flutter 4 → count=4, subsystem="flutter", non_interactive=false
• --yes 5 flutter → count=5, subsystem="flutter", non_interactive=true
• -y → count=default, subsystem=none, non_interactive=true
• (empty) → count=default, subsystem=none, non_interactive=false

Configuration

Load the merged config by running:

bash ${CLAUDE_SKILL_DIR}/bin/load-config.sh

This prints a single JSON object combining built-in plugin defaults with any user override at /.claude/make-better/config.json. All knobs (registry_path, review_stale_after_days, etc.) come from this object. Do not read any config file directly — always go through the loader.

Apply user count only if it is "⚠ Make Better expects Opus for best results, but this turn is executing on . Sub-agents (review/implement/scan) are still pinned to Opus via config, but the orchestrator's planning and merge-conflict decisions may be lower quality. Consider /model opus` and re-running."

Then:

• If non_interactive is true: log the warning and continue.
• Otherwise: call AskUserQuestion with options Continue anyway (default) and Abort — I'll switch to Opus and re-run. Proceed based on choice.

If your model is Opus, say nothing — silent on the happy path.

Non-interactive mode (--yes)

When non_interactive is true (set via --yes / -y / --auto), every step below that would normally pause for user input must instead resolve automatically. The rules:

1. Plan mode (Phase 2): skip entirely. Do not enter plan mode, do not call AskUserQuestion, do not show the "approve / modify / cancel" UI. Treat the computed plan as approved-as-is and proceed straight to Phase 3 (implementation).
2. Stale peer lockfiles (0.4): auto-delete and log one line: auto-removed stale lockfile (started_at ) due to --yes. Do not prompt.
3. Any other AskUserQuestion (merge conflict ambiguity in 3.5, ambiguous failure in Phase 4, anywhere else):

• If there is a documented safe default for that question, pick it and log: auto-picked "" because of --yes.
• If there is no safe default, skip the affected unit of work (the system, the section, whatever is at hand): mark its status in your in-memory plan as skipped_for_human, attach the question text and any relevant context as blocker, and continue with the rest. Do not stamp last_review for skipped systems.

1. Hard errors are still hard. Missing registry, dead lockfile that you can't safely remove, broken config — these still abort. --yes only suppresses prompts that have an answer the agent can produce.
2. status: needs_user_decision systems are still skipped from the candidate pool, regardless of --yes. Auto-mode does not retroactively decide what humans previously deferred.
3. Final report (Phase 5): add a Skipped — human decision needed section listing every system or sub-step that was deferred because there was no safe default. The user reviews this section after the unattended run.

If non_interactive is false (default), every prompt and plan mode behaves as documented in the rest of this skill.

Phase 0 — Bootstrap

0.1 Verify registry exists

Read ` (default docs/SYSTEMS.md). If the file is missing or has no ### ` headings:

> Stop with: "No systems registry found at `. Run /systems-discover` first to populate it."

Exit cleanly. Do not auto-invoke discovery.

0.2 Parse the registry

Walk the file line by line:

• ## — current section.
• ### — current system, attached to current section.
• - key: value under a system — set field.
• - value under a previously seen - areas: — append to that system's areas list.
• Other lines under a system — ignored.

Result: ordered list of systems with { section, name, last_review, status, blocker, areas, notes }.

0.3 Build candidate pool

Apply filters in order:

1. subsystem filter (semantic): if user provided a filter, look at section names AND system names AND notes. Decide which systems plausibly match. Be generous: flutter matches any system in a "Flutter App" section AND any system whose name or notes mention flutter. Use judgement.
2. drop status: needs_user_decision — these need manual resolution.
3. drop locked systems: read every /.systems-review.*.lock. Union their systems arrays. Drop those.
4. drop systems touched by the working tree: run git status --porcelain (and if needed git diff --name-only HEAD) to get the list of modified/staged/untracked files. For each remaining system, if any of its areas: paths overlaps with that file list (file lives under an area directory, or matches an area glob), drop the system. Goal: avoid merge conflicts between the in-progress user changes and the implementer's branch. A path overlap counts even for untracked files.
5. drop fresh systems: for each remaining system, if last_review is set AND newer than (today - review_stale_after_days), drop. Keep systems with no last_review.

If the pool is empty, tell the user with a brief diagnostic: "No stale systems matching `` (X total in registry, Y filtered out by status, Z locked by other runs, D touched by working-tree changes, W still fresh). Try a broader filter, commit/stash your changes, or use a shorter staleness window."

0.4 Detect stale lockfiles

Liveness is determined by age of started_at, not pid. Claude Code agents have no stable OS pid they can record (every Bash call is a fresh subshell), so a pid field is unreliable here — ignore it for liveness decisions.

For each peer lockfile (anyone's, not just yours):

• If started_at is within the last stale_lockfile_after_hours (default 3h): treat as a live peer run. Do nothing — its systems are already excluded by 0.3.3, and you proceed silently in parallel. Do not prompt the user.
• If started_at is older than that threshold: treat as stale (likely a crashed or aborted run). Prompt the user once:

> "Found stale lockfile ` from ` (older than h). Remove? (y/n)"

Do not auto-delete. Do not delete other runs' lockfiles unless the user approves here.

0.5 Sample N systems

Sample count systems from the pool. Weight toward oldest last_review (and treat null as "infinitely old" — those go first). If pool /.systems-review.-.lock`

Content:

{
  "started_at": "",
  "filter": "",
  "systems": ["", "..."]
}

Do not write a pid field — Claude Code agents have no stable OS pid (every Bash call is a fresh subshell, so any value would be meaningless). Liveness is determined entirely by started_at age (see 0.4).

Remember the lockfile path — you must delete it on every exit path. Wrap the rest of the run in try/finally semantics: if anything below throws, abort, delete the lockfile, surface the error.

0.7 Tell the user

Print a one-line status:

> "Picked N systems for review: . Filter: . Stale threshold: days. Lockfile: ."

Phase 1 — Review (parallel)

For each picked system, dispatch a review agent in parallel via the Agent tool. Cap concurrency at max_parallel_review_agents. If you have more systems than slots, run in waves.

For each review agent:

• subagent_type: general-purpose
• model: ` (default opus`)
• prompt: contents of ${CLAUDE_SKILL_DIR}/prompts/review-agent.md plus the system fields, the topic docs (read each path listed in _topics from the loader output — see "Topic resolution" below), the topic lists, repo root, and today's date.

Collect all returns. For each:

• verdict: "proceed" → keep the system in the active set.
• verdict: "empty_plan" → keep, but its plan section is the empty-plan template.
• verdict: "system_removed" → keep, but its plan section is the removed template; finalization will drop it from the registry.
• verdict: "needs_user_decision" → keep, but the section shown to the user explains the blocker; on approve, the registry is updated with the blocker (no implement phase for this system).

If any review agent throws or never returns sensibly, treat as needs_user_decision with blocker "review agent failed; rerun".

Phase 2 — Plan mode

Render the plan in the configured user_language. The plan is a compact summary — no file lists, no risks/tests sections. Just one bullet per change per system, brief but specific enough that the user knows what is being touched.

2.1 Render the plan

Group systems by their section (the H2 from SYSTEMS.md). Within a section, list each system with a compact bullet list:

## 

### 
- 
- 
- ...

### 
- ...

## 
...

Bullets describe what changes, not where or how. Example:

## Auth

### Google Auth (web → server)
- Unify 401 handling — single error mapper instead of two divergent paths
- Stop logging session token in the error path
- Add a unit test for the mapper

### Telegram Auth (bot → server)
- Replace silent retry on session refresh failure with explicit re-auth
- Update notes after recent middleware rename

Keep each bullet under ~120 characters. Skip items that are pure noise. Don't list every individual finding from every topic — fold related findings into one bullet when they describe the same change.

For systems with verdict "empty_plan": render only the system heading with _(no changes — review pass)_ and skip the bullet list.

For systems with verdict "system_removed": render _(system removed — no longer in code)_.

For systems with verdict "needs_user_decision": render _(needs decision: )_ — these get the blocker recorded but no implement run.

2.2 Overall summary (always at the end of the plan)

After all sections, render this block:

---

**Overall:** Found  issues across  systems.
-  bug fixes (auto-applied)
-  DRY refactors
-  architecture cleanups
-  consistency fixes
-  efficiency improvements
-  test additions / fixes
-  docs sync updates
-  completeness gaps
-  security issues               (only if any — drop the line if zero)

**Needs your attention:**
- : 
- ...

Rules for the Needs your attention section — this is the most important part of the plan:

• Bugs are auto-applied without flagging. Do NOT list bug fixes here.
• Logic / behavior changes MUST be flagged. Ideally a review pass changes no observable behavior, only structure. If anything in the plan changes runtime behavior — even subtly (different error type, different default, different timing, different log shape that downstream parses, different ordering of effects) — surface it here in plain language. Describe what the user/system would observe before vs after.
• Implicit decisions MUST be flagged. If the implementer would have to choose between two reasonable approaches (LWW vs vector-clock, string vs enum, etc.) and your plan picked one — say which one and why. The user can override before approving.
• Risky refactors that touch shared code paths used by other systems: flag them.
• API contract changes (even internal): flag them, name the contract.

If there is nothing to flag (pure bugs + structure-only refactors), write: _No behavior changes — bug fixes and structure-only refactors only._

2.3 Approval prompt — use AskUserQuestion

After printing the plan, call the AskUserQuestion tool to capture the user's decision via arrow-key + Enter UI. Build the questions argument with one question. The first option is always "approve as-is"; then 2–3 dynamically chosen options based on what is in the plan; finally a "modify / cancel" path.

If AskUserQuestion is not loaded yet, use ToolSearch with select:AskUserQuestion to load it before calling.

Build options like this (one question, multiple options, single-choice):

| Always present | Present only when applicable | |---|---| | Approve and execute (always option 1) | Drop behavior changes — apply only bug fixes and structure-only refactors (when the plan has any "Needs your attention" item that is a behavior change) | | Modify the plan (free-text follow-up) | Defer `** — skip this system, keep its last_review unchanged (when one system carries the bulk of risky changes) | | **Cancel** | **Drop the cross-cutting refactor in ** — keep the rest (when the plan includes a refactor that crosses several systems) | | | **Apply only ` — skip other sections this run (when there are 4+ systems and the user might want to start narrow) |

Pick 2–3 of the conditional options that best match the plan's actual risks. Skip "Approve" of course is always there. After "Approve", come the conditional ones, then "Modify" and "Cancel" as the last two.

Each option's label and description go to the user, so write them in user_language. Question header: short, like "Approve plan?" / "Утвердить план?".

2.4 Handle the response

| User picks | What you do | |---|---| | Approve and execute | Proceed to Phase 3. | | Drop behavior changes | For every system whose plan contains a behavior-change item flagged in "Needs your attention", remove that item from detailed_plan. Re-render the plan and re-prompt with AskUserQuestion. | | Defer ` | Remove that system from the active set (no last_review update for it). Re-render and re-prompt. | | Drop cross-cutting refactor / Apply only ` | Apply the corresponding scope reduction. Re-render and re-prompt. | | Modify the plan | Drop out of AskUserQuestion. Wait for the user's free-text instructions. Apply edits per the "Edit handling" rules below. After edits, re-render the plan and call AskUserQuestion again. | | Cancel | Skip Phase 3 and Phase 4 code path; still run cleanup (lockfile, etc.). |

Edit handling (free-text iteration after "Modify the plan")

When the user edits, classify:

• Trivial edits (drop a step, rename a path because the user knows it's better, mark a system as skip-and-don't-bump, reorder steps): silently update both user_spec (the rendered bullets) and detailed_plan (full instructions for the implementer) in your memory. Show a small diff. Re-call AskUserQuestion.
• Non-trivial edits (replace approach, add scope, "are you sure this is correct?"): investigate. You already hold raw_findings from each topic — start there. If you need fresh data on something narrow, dispatch ONE topic agent (the one most relevant) with a focused query. Then reply to the user with: consequences of their proposed change, alternatives if any look better, and end with "update the plan?". On confirmation, update the plan in your memory. Otherwise, leave it. Re-call AskUserQuestion.

If the user's edit pulls scope outside the system's areas:, warn them: "This change touches `, which belongs to system ` (or no registered system). Apply anyway?"

Phase 3 — Implement (parallel)

For every system with verdict: "proceed" (after edits) AND not skipped:

3.1 Compute the desired branch name

For each system, compute:

• system_slug = system name lowercased, non-alphanum → -
• desired_branch = /-/ (e.g. systems-review/all-20260504-110000/auth-middleware)

Hold this name; you'll need it after dispatch.

3.2 Dispatch the implement agent — try harness isolation first

Dispatch an implement agent via the Agent tool with the harness creating the worktree:

• subagent_type: general-purpose
• model: ` (default opus`)
• isolation: "worktree"
• prompt: contents

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: fivol
• Source: fivol/claude-make-better
• License: MIT

Install and usage instructions live in the source repository linked above.