Claude-Code-Game-Studios/.claude/docs/settings-guidance.md

# Settings Guidance — which value to recommend, and when

The **advisory** layer for project settings. This doc answers two questions no
other doc does:

1. **Which value should a skill recommend** for a given project or user?
2. **When should a skill proactively suggest changing** a setting already set?

## Boundary with its siblings — do not duplicate their content here

| Doc | Answers | Nature |
|---|---|---|
| `effects-map.md` | What each setting *does* | Descriptive |
| `config-resolution.md` | How a setting *resolves* (precedence chain) | Mechanical |
| **`settings-guidance.md`** (this file) | Which value to *recommend*, and *when* | Prescriptive |

Skills reference this doc **on demand**, only at a "recommend a setting" moment.
It is deliberately **not** a CLAUDE.md import — advisory content must not ride in
per-turn context (the same reason `context-management.md` was demoted).

---

## 1. The knob that matters most: `modes.rigor`

Almost every "what settings should I use?" question reduces to one choice:
`modes.rigor` (`minimal` | `standard` | `full`, default `minimal`). It fronts six
sub-knobs — `modes.workflow`, `docs.density`, `qa.level`, `modes.story_granularity`,
`modes.review_mode`, `team.size`. Recommend **rigor**, not the six; let the
expansion do the rest. Full expansion table lives in `effects-map.md § modes.rigor`
— do not restate it here.

`modes.automation` (`collaborative` | `guided` | `autonomous`) is a **separate
axis** — how often skills stop to confirm — and is *not* fronted by rigor. Pick it
by working style, not by game type (see § 5).

---

## 2. Archetype → rigor presets

Match the project to an archetype; recommend the paired rigor. These are starting
points, not verdicts — the user can always override.

| Archetype | Rigor | Why | Common override |
|---|---|---|---|
| Weekend jam / prototype / throwaway | `minimal` | Shipping beats recording; design lives in the maker's head | Bump one deep system: `workflow_overrides.system_overrides: {combat: full}` |
| Small solo / hobby game (arcade, puzzle, short narrative) | `minimal` → `standard` if it grows | Start light; add rigor when scope proves real | — |
| Focused commercial indie (platformer, roguelike, tactics, deckbuilder) | `standard` *(default)* | One well-understood loop; enough design to build correctly | "Comprehensive but compact": `rigor: full` + `docs.density: terse` |
| Systems-heavy / long-haul (open-world RPG, colony sim, immersive sim, 4X, survival) | `full` | Many interacting systems; a design mistake costs weeks | Solo dev: keep `full` on disk, set `review_mode: solo` locally |
| Live-service / competitive multiplayer | `full` + domain emphasis | Full pipeline *plus* netcode/security/live-ops | Raise `qa.level` / `testing.strict.*` for the online-critical types |

**The model:** the table picks a baseline; overrides handle the diagonal. Most real
projects are one baseline plus one or two deliberate exceptions.

---

## 3. Seeding rigor from a described concept

When the user has described their game (e.g. `/start` Phase 2 free text), map it to
an archetype and **pre-select** the recommendation rather than asking cold. Signals:

| Concept mentions… | Lean toward |
|---|---|
| open-world, RPG, sim, sandbox, faction, crafting, economy, MMO, multiplayer, "systems" | `full` |
| jam, weekend, prototype, "first game", small, "just trying", experiment | `minimal` |
| "release", "commercial", "on Steam", a single clear core loop | `standard` |
| *ambiguous / nothing above* | `standard` (the documented default) |

**Rules:** these are heuristics, never locks. Always confirm the pre-selection with
the user in their own terms ("Sounds like a big systems game — I'd suggest `full`
rigor; want that?"). If the user has **no concept yet** (exploring), do not seed
`full` — default `minimal`, and revisit once a concept exists.

"No concept yet" means **no signal**, not a particular onboarding path. A rough
one-line hint is still a description: if it trips the signals above, seed from the
signal. Only fall back to `minimal`-for-exploring when the user has given you
nothing to map. (`/start` Phase 3d states the same rule for its Path A/B branch —
the two must agree, since both drive the identical recommendation.)

---

## 4. When to recommend a *change* (adaptive triggers)

Bidirectional and **threshold-based**. Fire only on a threshold *crossing*, never
every session — that is what keeps this from becoming the nagging the `automation`
modes exist to eliminate.

| Trigger (crossing) | Direction | Detectable signal | Suggested action |
|---|---|---|---|
| Project grew past its band | ↑ raise | System-GDD count crosses ~9, or `src/` crosses the Production threshold, while rigor is `minimal` | "You're at N systems on `rigor: minimal` — most projects this size run `standard`. Revisit? → `/settings`" |
| Stage advanced into Production | ↑ raise | `/gate-check` PASS into Production while rigor is `minimal` | Same, offered once at the gate |
| User sounds overwhelmed by process | ↓ lower | Phrases like "too many steps", "so much documentation", "overwhelmed" — *and* rigor is not already `minimal` | "If the required-doc list feels heavy, a lower rigor trims it → `/settings modes.rigor=standard`" |
| Chosen rigor mismatches described scope | flag once | Onboarding pick contradicts the Phase-2 description | State it in one sentence, offer `/settings`, do not re-ask |

**Frequency guard:** the crossing *is* the gate. Because the hosts (`/gate-check` on
PASS, `/help` on request) are themselves infrequent, no persistent "already nudged"
state is needed — but never emit the same suggestion twice in one session.

---

## 5. Which skills reference this doc, and when

| Skill | Moment | Sections used |
|---|---|---|
| `/start` | Phase 3d/4 — choosing rigor | § 2 (presets), § 3 (seed from concept) |
| `/help` | escalation footer when user sounds stuck/overwhelmed | § 4 (lower trigger) |
| `/gate-check` | on PASS into a new stage | § 4 (raise trigger) |
| `/settings` | view output — further reading | § 2 (choosing a value) |

Each skill carries a **one-line pointer** to this doc, not a copy of its tables.

---

## 6. How to phrase a recommendation

- **Recommend, don't dictate.** State the suggestion and the reason in one line;
  the user decides. (`collaborative`/`guided` require this; even `autonomous`
  treats a rigor change as a `schema_changes` decision and asks.)
- **Always route to `/settings`** — never edit `project.yaml` as a side effect of a
  recommendation.
- **One line, then stop.** A nudge is a nudge, not a lecture.