# Skill: content-balance

Use this skill for mission/sector/upgrade balancing and authored data changes.

## When to use

- Tuning mission rewards, penalties, target counts, durations, or time limits.
- Adjusting sector hazard/enemy/cargo authored values.
- Balancing upgrade costs and effects while preserving gameplay progression.

## When not to use

- Mechanics requiring algorithm/code changes in systems (use `gameplay-change`).
- State/menu screen flow updates (use `state-flow-ui`).

## Inspect first (required)

1. `source/content/missions.lua`
2. `source/content/sectors.lua`
3. `source/content/upgrades.lua`
4. `source/systems/mission_runtime.lua`
5. `source/systems/game_state.lua`
6. `source/core/constants.lua`
7. `AGENT.md`

## Workflow

1. Define target balancing intent (for example: mission pacing, economy pressure, upgrade unlock cadence).
2. Edit only relevant content tables.
3. Cross-check compatibility:
   - Mission `archetype` values are supported by `mission_runtime`.
   - `targetCount`/`duration`/`timeLimit` combinations are achievable.
   - `reward` and `failurePenalty` keep economy progression coherent.
   - Upgrade `apply` keys match actual loadout fields used by systems.
4. Keep IDs stable. If new IDs are added, ensure references remain consistent.
5. Run build and deterministic harness checklist.
6. Run optional manual simulator smoke for affected content paths.

## Definition of done

- `pdc source game.pdx` succeeds.
- `lua tools/sim/run.lua` succeeds.
- Harness-backed scenarios completed:
  1. Start at least one affected mission and confirm objective progression.
  2. Trigger mission success or timeout failure and validate debrief deltas.
  3. Buy at least one affected upgrade and confirm gameplay impact appears.
- Optional manual simulator scenarios completed when balancing changes are broad/high-risk.
- Summary documents:
  - changed content entries
  - balancing rationale
  - any observed side effects

## Common pitfalls

- Archetype/objective mismatch (content defines unsupported objective semantics).
- Rewards/penalties creating negative-credit dead-ends too early.
- Upgrade effects using keys not consumed in runtime systems.
- Changing content IDs that existing save snapshots rely on.