Meta Refresh

Read-only phases

No files are written in this section.

Phase 1 — Categorize

If a server host was provided, fetch active plugins:

ssh <host> "ls {SERVER_PLUGINS_DIR}"

Note server-side companions — affects verdicts for client mods with server-side counterparts (e.g. DHSupport enables DH LOD sync, Lithium/Krypton have server-side performance components).

Read <instance>/.minecraft/mods/ (include .disabled files). Assign each mod to exactly one category:

Output: category → [mod list] map.

Phase 2 — Parallel Category Agents

REQUIRED SUB-SKILL: superpowers:dispatching-parallel-agents — use it to dispatch and manage all category agents.

Run one general-purpose agent per non-library, non-disabled category. Dispatch all with run_in_background: true.

Read ./category-agent-prompt.md (in this skill's directory) for the full agent prompt template. Inject per-agent values (category name, user mods, MC version, modloader, server-side companions) from Phase 1.

When constructing sub-agent prompts, resolve all relative paths (like ../compat-check/SKILL.md) to absolute paths using this skill's base directory before injecting.

Wait for all agents to complete before Phase 3.

Phase 3 — Synthesize

• Merge all Category Reports into one list.
• Resolve conflicts (same mod recommended by two agents — use the one with more supporting data).
• De-duplicate gap candidates.

Phase 4 — Upgrade Plan

Build the numbered upgrade plan from all category reports. Read ./upgrade-plan-format.md (in this skill's directory) for the exact output format and table rules.

After presenting the plan, tell the user:

Reply with:

• "approve all" — apply every proposed change
• "approve 1,3" — apply only items #1 and #3
• "skip 2" — approve all except #2
• "cancel" — abort, no changes made

No files are written until the user explicitly responds.

Write phases

Files are written only after the user responds to the upgrade plan.

Phase 5 — Write Decision Doc

Decision doc path: ./minecraft-audits/prism-<instance-name>-YYYY-MM-DD.md

Create ./minecraft-audits/ if it doesn't exist. Create the file if it doesn't exist. If it already exists (created by audit), append to it.

Header (write at top if creating):

# Minecraft Audit — YYYY-MM-DD
Instance: <name>
MC Version: <version>
Modloader: <loader>

Meta decisions section (always append):

## Meta decisions
| # | Action | Mod | Alternative | Decision |
|---|--------|-----|-------------|----------|
| 1 | ADD | Lithium | — | approved |
| 2 | REPLACE | flow | Smooth Gui | skipped |
| 3 | REMOVE | noisium | — | approved |

Use approved, skipped, or cancelled in the Decision column.

Phase 6 — Chain to Version-Refresh

After writing the decision doc, say:

Meta audit complete. Decision doc saved to ./minecraft-audits/prism-<instance-name>-YYYY-MM-DD.md.

1. Proceed — continue to version-refresh
2. Cancel — stop here

• If 1: Say "Invoking version-refresh." and invoke it, passing the decision doc path and instance name.
• If 2: Ask: "1. Delete decision doc — keep tidy, or 2. Keep decision doc — save for a future run?" — act on response.

Failure Handling

If any phase produces unexpected results — malformed agent output, Modrinth API errors, agents returning empty or garbled Category Reports — invoke superpowers:systematic-debugging before retrying or escalating to the user.

Common Mistakes

• Recommending mods without running compat-check — every mod verdict and every gap candidate MUST have a verified compat status. This is the #1 failure mode.
• Trusting Modrinth search facets as proof of exact-version builds — the versions:X facet uses minor-series matching, not exact matching. Always call the /version endpoint to confirm.
• Writing files before user approval — Phases 1-4 are strictly read-only. No decision doc writes until the user responds to the upgrade plan.
• Recommending mods that violate vanilla+ profile — never recommend minimap, world map, block/entity info overlays, or mods that reveal non-vanilla information.

Meta Signal Sources (priority order)

1. Modrinth download count + date_modified for target MC version — primary signal
2. Presence in DisruptiveBuilds REFINED or PLUS pack — validation signal
3. GitHub stars + last push date — tiebreaker for close calls