Que fait balance ?
<skill-dir> is the folder that holds this SKILL.md, and <plugin-root> is two folders above it. Replace them with real paths in commands. (In Claude Code they are ${CLAUDE_SKILL_DIR} and ${CLAUDE_PLUGIN_ROOT}.)
Input: a feature or system, such as weapons, daily quest rewards or
levels 1-50. Output: balance sheets for it in the workbook, a report page
at config: Balance → Report with copy-ready prompts for any data still
needed, and, after approval, game code that matches the workbook. When that
data arrives, the same report is updated.
Read <plugin-root>/shared/conventions.md and the repo config first.
Then read <skill-dir>/references/workbook-format.md (the workbook
contract) and <skill-dir>/references/balance-checks.md (what to
check).
Modes
- Default: uses the team's live data where it exists, and requests what's missing.
--report-only: proposes changes without applying them (step 7).--no-data: for when there's no player data to use: a game that hasn't launched, a new system with no history, or no access to analytics. It's on automatically when config: Live data isnone; say so in the report. In this mode:- never request analytics that don't exist (step 4a is replaced);
- lean harder on benchmarks and simulation (steps 4b and 7);
- mark every target
no player data, because no player has tested it; - write a data plan instead of data requests (step 9): what to measure, the thresholds for the first real data, and the prompts to run once data exists.
Core principle
The workbook is the balancing database. You make decisions from its values, from the team's live data and from competitor benchmarks, never from fresh guesses. A simulation projects what a change will do; it doesn't say what the right number is. You write to the workbook only through the script, and you never overwrite a value the GD set without their approval.
BB="<skill-dir>/scripts/run.sh" # creates its own venv with openpyxl on first run
"$BB" <command> <workbook> … # init | dump | diff | ack | owners | apply | link | sync-status | mark-synced
Every command prints JSON. The exit codes are: 3 for unacknowledged GD edits, 4 for a GD-owned cell without approval, 5 when the workbook is open in Excel, and 6 when the workbook holds charts or images that would be lost. Handle each one as the steps below describe. Never get around them, for example by writing the file another way.
1. Analyze the game
Before judging any number, understand the system as the code runs it:
- Find every tunable value of the feature in the code, remote config and data files: stats, costs, rewards, timers, caps, weights, curves and formulas.
- Trace how they combine: damage formulas, multiplier stacking order, reward rolls, level gates, and what feeds what (the loops).
- Note the systems it touches, such as currencies, other items or progression, and the values those already use.
2. Load the workbook, the GD's edits and the last report
If the workbook at config: Balance → Workbook doesn't exist yet, go to step 3.
-
If this system already has a report, read it. For every open
data-drrequest, look for its file under the expected name, and use what has arrived (see step 10). -
Run
diff. If there are pending GD edits, show them to the user in a short table (sheet, id, field, old → new), then runack. They are now GD-owned and logged asby=GD. Treat them as intended design: balance around them. If one of them breaks a target, report it in step 7 and propose a change, but don't revert it. -
If it exits 5, ask the GD to save and close the file, and wait. If it exits 6, explain that charts and images must move to a separate workbook.
-
Run
dumpandownersto get the current values and to know which ones are the GD's. -
Values that differ between the code and the workbook: run
sync-status, and also compare the code with thelast_synced_value. A value that changed in the code but not in the workbook is a code-side edit. Ask which one is right; don't pick silently.
3. Propose the balance sheets
Every system you balance gets sheets in the workbook. Don't skip this
because the values look fine or because the run is --report-only.
- Draft the sheet plan from step 1: one sheet per system, one row per thing,
the input columns (blue, values from the code today) and the derived
columns (formulas such as value per cost or time to next upgrade), plus the
Targetsrows the checks need. Show it as a short table: Sheet, Rows, Inputs, Derived. - No workbook yet: ask with the question tool. The options are: create
the workbook at the config path with these sheets (Recommended); create it
at another path; or don't create one and only report, which means the GD
can't edit the values and the next run starts from scratch. On a yes, run
initand write the path into the config if it was a placeholder. - Workbook exists, but the system has no sheet, or rows or columns are missing: list what you'll add, then add it. Adding rows and sheets that copy the code is not a balance change, so it needs no approval beyond the plan.
- Write them with
apply: inputs as values, derived metrics as formulas with{field}placeholders, never column letters (see workbook-format.md). Use the reasonimport from code. - Link every imported value to its code location with
link, thenmark-syncedthe imported keys, because the code and the workbook match at that point.
4. Gather evidence: our data and competitor benchmarks
Do this on every run, before setting targets. Don't wait to be asked.
4a. Request the team's data (Observed)
For content that's live, the team's own numbers beat everything else.
--no-data: skip the analytics requests. Use only data the team
already has from playtests or test builds, if the repo or the user has any,
and label it Observed (playtest <date>, n=<players>), because a few testers
are not the market. Then go to 4b.
- Look first in config: Live data and the repo's data folders for exports that cover the current build and the last 14 days or more.
- If they're missing or stale, pull them yourself when the config gives you
access (such as a BigQuery export or a bucket). Otherwise, write a data
request for each one, as conventions §5b describes: a copy-ready prompt
naming the tool, the report, the metric, the filters, the absolute date
range, the minimum sample, the CSV columns and the file name to save it
as. Don't wait for the data: carry on with benchmarks, mark each gap
DATA NEEDED: DRn, and mark the targets that rest on benchmarks alone as lower confidence. - Interrogate every number before using it: the sample size and window, whether the event fires when you think it does (retries, resume from background), mix shifts in traffic, the build filter, and incomplete data for today. Follow the repo's own analytics rules where they exist, and state the row count and source of each number you use.
4b. Research competitors (Benchmark)
Research automatically. Don't ask first.
- Which games: the reference game from the config, plus 2–4 games that
rank high in the same genre now, starting with the "also considered" list
from the config's reference-game line. Use WebSearch where it's available.
With
--no-data, use 4–6 games, because benchmarks are the main outside evidence, and look for published numbers for the genre too (retention by day, session length, early-level funnels, soft-launch results). - What to find: the same values this system tunes. For example: prices and pack sizes, reward amounts and cadence, timers and caps, cost and income curves, energy or lives, ad reward caps, and difficulty pacing.
- Where to look, from most to least reliable: official patch notes and store listings (IAP prices), datamined or public config, wikis, and deconstructions such as Deconstructor of Fun, GameRefinery, Naavik or mobilegamer.biz. Use forum and video sources only when nothing else exists, and mark them low confidence.
- Privacy: a search names the competitor games and the genre. It never names this repo's game, its unreleased features or its internal numbers.
- Normalize the units before comparing: per minute of play, per session, per day, or a USD price tier. Note the context of each number, such as the level, the day or the tier.
- Write each number into the
Benchmarkssheet withapply(reason:research), with its game, source URL, the date you accessed it and a confidence level (high, medium or low). - One game is a reference, not a benchmark. A benchmark range needs at least two games.
- If WebSearch isn't available, say so, ask the user for competitor numbers they have, and fall back on the genre anchors in the repo's CLAUDE.md.
5. Set targets
Every balance judgment needs a target. Read Targets. For each check that has
no target, propose one, in this order:
- targets the GD already set;
- our observed data, for live content;
- the reference game's benchmark;
- the competitor benchmark range, using its median and spread;
- the genre anchors in the repo's CLAUDE.md.
With --no-data, step 2 doesn't exist, so targets come from the GD, the
reference game, the competitor range and the genre anchors, and each one's
notes says no player data.
Add the targets with apply, and give each one a source that names where
it came from, such as Benchmark (3 games: A, B, C; 2026-11-18). Targets set
by the GD are GD-owned like any other cell.
6. Detect problems
Run the checks in balance-checks.md that apply: power and value curves,
scaling, synergies and exploits, economy flow (the non-payer, the 10x failer
and the hoarder), difficulty, new content against existing content, and our
values against the benchmarks.
Compute metrics in Python from the dumped input values. Don't trust a stale
cached formula value. Write the results into Targets.actual, with source
and status, through apply.
7. Validate and propose
For each problem, design the smallest change that brings the metric back within its target. Back it with the strongest evidence you have, and give every proposal at least one outside anchor (our data or a benchmark), or say there isn't one:
- Observed: our live data shows the problem, or a past change of the same value shows its effect.
- Benchmark: where the proposed value sits in the competitor range.
- Measured: the repo's simulations or tests (config: Simulations and tests). If none exists and the question needs one, write a small Python simulation in the scratchpad, such as a Monte Carlo of reward rolls or a 30-day economy for each player type. Feed it observed or benchmark inputs, such as the real attempts-per-level distribution. Label any input you assumed, and report the seed and number of runs.
- Estimated: closed-form maths from the workbook values.
--no-data: simulation carries more of the weight, so make it honest:
- Build the player models (the non-payer, the 10x failer, the hoarder, and a typical player) from benchmark inputs: sessions per day, session length, attempts per level, ad opt-in. Name the source of each input.
- Run a sensitivity check: vary each assumed input across its benchmark range, and report which conclusions hold across the whole range and which flip. Propose only the changes that hold. List the ones that flip as "decide when data exists".
- Prefer values that are easy to change later, such as remote config, over values baked into the build.
Always label each result Observed, Benchmark, Measured or Estimated. Never present an estimate as a test result, and never present a simulation run on assumed inputs as proof. A proposal that rests only on a simulation is low confidence: say so, and name the data that would settle it.
Present the proposals as a table with the columns Sheet/id/field, Current, Proposed, Benchmark range, Why, Evidence (and its kind) and Owner (AI or GD). Then:
- AI-owned values: apply them once the user has approved the batch. Where the trade-off is real, ask with the question tool and give 3 or more options, such as nerf it, buff its peers, or raise its cost.
- GD-owned values: always ask, one question per value or per group of
related values. Send
"approved": trueonly for the exact values the user approved. --report-only: stop after the table. Write nothing except the sheets from step 3, theBenchmarksrows,Targets.actualand the report page.
Then run apply with a reason on every change. The reason should be
specific, for example "smg dps_per_1k 31% over tier-2 curve and above the
3-game benchmark; cost 1200→1500 puts it at +4%".
8. Sync into the game
Once the changes are applied to the workbook:
- Run
sync-status. For eachpendingrow, change the value at itscode_refin the code or remote-config default. Remote-config values that are live go to the user as a payload to paste: give them the JSON, because you don't change remote config yourself. - Run the config's typecheck and the feature's tests, then
mark-syncedthe rows you changed. - If a code change can't follow the workbook, for example because the code
computes the value, update the
code_refand tell the user.
9. Report
Write the report page at config: Balance → Report, starting from
<skill-dir>/assets/balance-report-template.html and following the HTML
rules in the conventions. If the system already has a report, update it and
bump its revision; don't create a second file. It holds:
- In short: at most 4 bullets.
- The evidence used: the data exports (source, range, rows), the games researched, and the simulations (seed, runs, which inputs are assumed).
- Findings, each with its evidence kind, and proposals with their status (applied, approved by GD, or pending approval).
- What was synced to code, and the remote-config payload the user has to push, with a Copy button.
- Data needed: one copy-ready prompt per open request (conventions §5b).
- What to watch after release: the metric, its baseline and its source.
- With
--no-data, a data plan in place of open data requests:- Measure: each target and the analytics event that measures it. Flag any event the game doesn't fire yet, because a target with no event can't be checked later.
- First-data thresholds: for each key metric, the value that means "keep", "tune" or "stop" once real data arrives, taken from the benchmarks.
- Future prompts: the copy-ready data prompts to run once there is
data, each with
data-status="future". Their date ranges say "the first 14 days with data, from the release or soft launch", since the dates aren't known yet.
In chat, give the report path, the workbook path, the sheets created or
extended, the GD edits acknowledged, the changes applied, and every open data
prompt as its own code block, so it can be copied straight from the chat.
End with one line: "Send me the files, paste the data or drop them under the
names in the prompts, and I'll update the report." With --no-data, list
the events still missing instead of the prompts, and end with: "Once there's
player data, run /gd:balance <system> without --no-data, and the future
prompts become data requests."
10. When the data arrives
When the user provides data (in this session or a later run), follow conventions §5b, plus:
- Write the observed values into the workbook through
apply:Targets.actualwith anObserved (…)source, and any target that should now come from our data instead of a benchmark. - Re-run the checks the data touches (step 6), and redo the proposals it changes (step 7). A change already applied that the data contradicts gets a new proposal, not a silent revert. GD-owned values still need approval.
- Update the report in place: the evidence, findings and proposals, and the request marked received.
- When player data first exists: the first run without
--no-data(or after config: Live data stops beingnone) turns thefutureprompts into open requests with real dates, compares the first numbers with the thresholds, and replaces theno player datatargets that our data now covers.
Don't commit unless asked. The workbook and its Changelog are the record of
what changed; add .history/ to .gitignore if it isn't there.