Skills refinement: improve formatting, phase structure, and trigger descriptions across 9 skills

- balance-check: rewrote as explicit phases with domain routing table; expanded trigger hints
- scope-check: restructured into numbered phases for clarity
- adopt, review-all-gdds, help, project-stage-detect: add argument mode headers or trigger hints
- gate-check, sprint-status, story-readiness: minor wording and structure improvements

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.claude/skills/adopt/SKILL.md

@@ -24,6 +24,9 @@ wrong internal format.
 **Output:** `docs/adoption-plan-[date].md` — a persistent, checkable migration plan.
 
 **Argument modes:**
+
+**Audit mode:** `$ARGUMENTS[0]` (blank = `full`)
+
 - **No argument / `full`**: Complete audit — all artifact types
 - **`gdds`**: GDD format compliance only
 - **`adrs`**: ADR format compliance only

.claude/skills/balance-check/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: balance-check
-description: "Analyzes game balance data files, formulas, and configuration to identify outliers, broken progressions, degenerate strategies, and economy imbalances. Use after modifying any balance-related data or design."
+description: "Analyzes game balance data files, formulas, and configuration to identify outliers, broken progressions, degenerate strategies, and economy imbalances. Use after modifying any balance-related data or design. Use when user says 'balance report', 'check game balance', 'run a balance check'."
 argument-hint: "[system-name|path-to-data-file]"
 user-invocable: true
 allowed-tools: Read, Glob, Grep
@@ -8,44 +8,68 @@ context: fork
 agent: economy-designer
 ---
 
-When this skill is invoked:
+## Phase 1: Identify Balance Domain
 
-1. **Identify the balance domain** from the argument.
+Determine the balance domain from `$ARGUMENTS[0]`:
 
-2. **Read relevant data files** from `assets/data/` and `design/balance/`.
+- **Combat** → weapon/ability DPS, time-to-kill, damage type interactions
+- **Economy** → resource faucets/sinks, acquisition rates, item pricing
+- **Progression** → XP/power curves, dead zones, power spikes
+- **Loot** → rarity distribution, pity timers, inventory pressure
+- **File path given** → load that file directly and infer domain from content
 
-3. **Read the design document** for the system being checked from `design/gdd/`.
+If no argument, ask the user which system to check.
 
-4. **Perform analysis**:
+---
 
-   For **combat balance**:
+## Phase 2: Read Data Files
-   - Calculate DPS for all weapons/abilities at each power tier
-   - Check time-to-kill at each tier
-   - Identify any options that dominate all others (strictly better)
-   - Check if defensive options can create unkillable states
-   - Verify damage type/resistance interactions are balanced
 
-   For **economy balance**:
+Read relevant files from `assets/data/` and `design/balance/` for the identified domain.
-   - Map all resource faucets and sinks with flow rates
+Note every file read — they will appear in the Data Sources section of the report.
-   - Project resource accumulation over time
-   - Check for infinite resource loops
-   - Verify gold sinks scale with gold generation
-   - Check if any items are never worth purchasing
 
-   For **progression balance**:
+---
-   - Plot the XP curve and power curve
-   - Check for dead zones (no meaningful progression for too long)
-   - Check for power spikes (sudden jumps in capability)
-   - Verify content gates align with expected player power
-   - Check if skip/grind strategies break intended pacing
 
-   For **loot balance**:
+## Phase 3: Read Design Document
-   - Calculate expected time to acquire each rarity tier
-   - Check pity timer math
-   - Verify no loot is strictly useless at any stage
-   - Check inventory pressure vs acquisition rate
 
-5. **Output the analysis**:
+Read the GDD for the system from `design/gdd/` to understand intended design targets,
+tuning knobs, and expected value ranges. This is the baseline for "correct" behaviour.
+
+---
+
+## Phase 4: Perform Analysis
+
+Run domain-specific checks:
+
+**Combat balance:**
+- Calculate DPS for all weapons/abilities at each power tier
+- Check time-to-kill at each tier
+- Identify any options that dominate all others (strictly better)
+- Check if defensive options can create unkillable states
+- Verify damage type/resistance interactions are balanced
+
+**Economy balance:**
+- Map all resource faucets and sinks with flow rates
+- Project resource accumulation over time
+- Check for infinite resource loops
+- Verify gold sinks scale with gold generation
+- Check if any items are never worth purchasing
+
+**Progression balance:**
+- Plot the XP curve and power curve
+- Check for dead zones (no meaningful progression for too long)
+- Check for power spikes (sudden jumps in capability)
+- Verify content gates align with expected player power
+- Check if skip/grind strategies break intended pacing
+
+**Loot balance:**
+- Calculate expected time to acquire each rarity tier
+- Check pity timer math
+- Verify no loot is strictly useless at any stage
+- Check inventory pressure vs acquisition rate
+
+---
+
+## Phase 5: Output the Analysis
 
 ```
 ## Balance Check: [System Name]
@@ -73,21 +97,23 @@ When this skill is invoked:
 [Specific values with suggested adjustments and rationale]
 ```
 
-6. **Fix & Verify Cycle**
+---
 
-   After presenting the report, ask:
+## Phase 6: Fix & Verify Cycle
 
-   > "Would you like to fix any of these balance issues now?"
+After presenting the report, ask:
 
-   If yes:
+> "Would you like to fix any of these balance issues now?"
-   - Ask which issue to address first (refer to the Recommendations table by priority row)
-   - Guide the user to update the relevant data file in `assets/data/` or formula in `design/balance/`
-   - After each fix, offer to re-run the relevant balance checks for that system to verify the fix did not introduce new outliers or degenerate interactions
-   - If the fix changes a tuning knob that is defined in a GDD or referenced by an ADR, remind the user:
-     > "This value is defined in a design document. Run `/propagate-design-change [path]` on the affected GDD to find downstream impacts before committing."
 
-   If no:
+If yes:
-   - Summarize the open issues and suggest saving the report to `design/balance/balance-check-[system]-[date].md` for later.
+- Ask which issue to address first (refer to the Recommendations table by priority row)
+- Guide the user to update the relevant data file in `assets/data/` or formula in `design/balance/`
+- After each fix, offer to re-run the relevant balance checks to verify no new outliers were introduced
+- If the fix changes a tuning knob defined in a GDD or referenced by an ADR, remind the user:
+  > "This value is defined in a design document. Run `/propagate-design-change [path]` on the affected GDD to find downstream impacts before committing."
 
-   End with:
+If no:
-   > "Re-run `/balance-check` after fixes to verify."
+- Summarize open issues and suggest saving the report to `design/balance/balance-check-[system]-[date].md` for later
+
+End with:
+> "Re-run `/balance-check` after fixes to verify."

.claude/skills/gate-check/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: gate-check
-description: "Validate readiness to advance between development phases. Produces a PASS/CONCERNS/FAIL verdict with specific blockers and required artifacts."
+description: "Validate readiness to advance between development phases. Produces a PASS/CONCERNS/FAIL verdict with specific blockers and required artifacts. Use when user says 'are we ready to move to X', 'can we advance to production', 'check if we can start the next phase', 'pass the gate'."
 argument-hint: "[target-phase: systems-design | technical-setup | pre-production | production | polish | release]"
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Bash, Write
+context: fork
 ---
 
 # Phase Gate Validation
@@ -33,6 +34,8 @@ The project progresses through these stages:
 
 ## 1. Parse Arguments
 
+**Target phase:** `$ARGUMENTS[0]` (blank = auto-detect current stage, then validate next transition)
+
 - **With argument**: `/gate-check production` — validate readiness for that specific phase
 - **No argument**: Auto-detect current stage using the same heuristics as
   `/project-stage-detect`, then validate the NEXT phase transition

.claude/skills/help/SKILL.md

@@ -4,6 +4,8 @@ description: "Analyzes what is done and the users query and offers advice on wha
 argument-hint: "[optional: what you just finished, e.g. 'finished design-review' or 'stuck on ADRs']"
 user-invocable: true
 allowed-tools: Read, Glob, Grep
+context: |
+  !echo "=== Live Project State ===" && echo "Stage: $(cat production/stage.txt 2>/dev/null | tr -d '[:space:]' || echo 'not set')" && echo "Latest sprint: $(ls -t production/sprints/*.md 2>/dev/null | head -1 || echo 'none')" && echo "Session state: $(head -5 production/session-state/active.md 2>/dev/null || echo 'none')"
 ---
 
 # Studio Help — What Do I Do Next?

.claude/skills/project-stage-detect/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: project-stage-detect
-description: "Automatically analyze project state, detect stage, identify gaps, and recommend next steps based on existing artifacts."
+description: "Automatically analyze project state, detect stage, identify gaps, and recommend next steps based on existing artifacts. Use when user asks 'where are we in development', 'what stage are we in', 'full project audit'."
 argument-hint: "[optional: role filter like 'programmer' or 'designer']"
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Bash
@@ -93,6 +93,7 @@ Use template: `.claude/docs/templates/project-stage-report.md`
 
 **Date**: [date]
 **Stage**: [Concept/Systems Design/Technical Setup/Pre-Production/Production/Polish/Release]
+**Stage Confidence**: [PASS — clearly detected / CONCERNS — ambiguous signals / FAIL — critical gaps block progress]
 
 ## Completeness Overview
 - Design: [X%] ([N] docs, [gaps])

.claude/skills/review-all-gdds/SKILL.md

@@ -29,6 +29,9 @@ completeness. This skill reviews the *relationships* between all GDDs.
   inherits those inconsistencies)
 
 **Argument modes:**
+
+**Focus:** `$ARGUMENTS[0]` (blank = `full`)
+
 - **No argument / `full`**: Both consistency and design theory passes
 - **`consistency`**: Cross-GDD consistency checks only (faster)
 - **`design-theory`**: Game design holism checks only

.claude/skills/scope-check/SKILL.md

@@ -1,73 +1,126 @@
 ---
 name: scope-check
-description: "Analyze a feature or sprint for scope creep by comparing current scope against the original plan. Flags additions, quantifies bloat, and recommends cuts."
+description: "Analyze a feature or sprint for scope creep by comparing current scope against the original plan. Flags additions, quantifies bloat, and recommends cuts. Use when user says 'any scope creep', 'scope review', 'are we staying in scope'."
 argument-hint: "[feature-name or sprint-N]"
 user-invocable: true
-allowed-tools: Read, Glob, Grep
+allowed-tools: Read, Glob, Grep, Bash
-context: |
+context: fork
-  !git diff --stat HEAD~20 2>/dev/null
 ---
-When this skill is invoked:
 
-1. **Read the original plan** — Find the relevant document:
+# Scope Check
-   - If a feature name: read the design doc from `design/gdd/`
-   - If a sprint number: read the sprint plan from `production/sprints/`
-   - If a milestone: read the milestone definition from `production/milestones/`
 
-2. **Read the current state** — Check what has actually been implemented or is in progress:
+Compares original planned scope against current state to detect, quantify, and triage
-   - Scan the codebase for files related to the feature/sprint
+scope creep. Read-only — never edits files without approval.
-   - Read git log for commits related to this work
-   - Check for TODO comments that indicate unfinished scope additions
 
-3. **Compare original vs current scope**:
+**Argument:** `$ARGUMENTS[0]` — feature name, sprint number, or milestone name.
 
-   ```markdown
+---
-   ## Scope Check: [Feature/Sprint Name]
-   Generated: [Date]
 
-   ### Original Scope
+## Phase 1: Find the Original Plan
-   [List of items from the original plan]
 
-   ### Current Scope
+Locate the baseline scope document for the given argument:
-   [List of items currently implemented or in progress]
 
-   ### Scope Additions (not in original plan)
+- **Feature name** → read `design/gdd/[feature].md` or matching file in `design/`
-   | Addition | Who Added | When | Justified? | Effort |
+- **Sprint number** (e.g., `sprint-3`) → read `production/sprints/sprint-03.md` or similar
-   |----------|-----------|------|------------|--------|
+- **Milestone** → read `production/milestones/[name].md`
-   | [item] | [commit/person] | [date] | [Yes/No/Unclear] | [S/M/L] |
 
-   ### Scope Removals (in original but dropped)
+If the document is not found, report the missing file and stop. Do not proceed without
-   | Removed Item | Reason | Impact |
+a baseline to compare against.
-   |-------------|--------|--------|
-   | [item] | [why removed] | [what's affected] |
 
-   ### Bloat Score
+---
-   - Original items: [N]
-   - Current items: [N]
-   - Items added: [N] (+[X]%)
-   - Items removed: [N]
-   - Net scope change: [+/-N] ([X]%)
 
-   ### Risk Assessment
+## Phase 2: Read the Current State
-   - **Schedule Risk**: [Low/Medium/High] — [explanation]
-   - **Quality Risk**: [Low/Medium/High] — [explanation]
-   - **Integration Risk**: [Low/Medium/High] — [explanation]
 
-   ### Recommendations
+Check what has actually been implemented or is in progress:
-   1. **Cut**: [Items that should be removed to stay on schedule]
-   2. **Defer**: [Items that can move to a future sprint/version]
-   3. **Keep**: [Additions that are genuinely necessary]
-   4. **Flag**: [Items that need a decision from producer/creative-director]
-   ```
 
-4. **Output the scope check** with a clear verdict:
+- Scan the codebase for files related to the feature/sprint
-   - **On Track**: Scope within 10% of original
+- Read git log for commits related to this work (`git log --oneline --since=[start-date]`)
-   - **Minor Creep**: 10-25% scope increase — manageable with adjustments
+- Check for TODO/FIXME comments that indicate unfinished scope additions
-   - **Significant Creep**: 25-50% scope increase — need to cut or extend timeline
+- Check active sprint plan if the feature is mid-sprint
-   - **Out of Control**: >50% scope increase — stop and re-plan
+
+---
+
+## Phase 3: Compare Original vs Current Scope
+
+Produce the comparison report:
+
+```markdown
+## Scope Check: [Feature/Sprint Name]
+Generated: [Date]
+
+### Original Scope
+[List of items from the original plan]
+
+### Current Scope
+[List of items currently implemented or in progress]
+
+### Scope Additions (not in original plan)
+| Addition | Source | When | Justified? | Effort |
+|----------|--------|------|------------|--------|
+| [item] | [commit/person] | [date] | [Yes/No/Unclear] | [S/M/L] |
+
+### Scope Removals (in original but dropped)
+| Removed Item | Reason | Impact |
+|-------------|--------|--------|
+| [item] | [why removed] | [what's affected] |
+
+### Bloat Score
+- Original items: [N]
+- Current items: [N]
+- Items added: [N] (+[X]%)
+- Items removed: [N]
+- Net scope change: [+/-N] ([X]%)
+
+### Risk Assessment
+- **Schedule Risk**: [Low/Medium/High] — [explanation]
+- **Quality Risk**: [Low/Medium/High] — [explanation]
+- **Integration Risk**: [Low/Medium/High] — [explanation]
+
+### Recommendations
+1. **Cut**: [Items that should be removed to stay on schedule]
+2. **Defer**: [Items that can move to a future sprint/version]
+3. **Keep**: [Additions that are genuinely necessary]
+4. **Flag**: [Items that need a decision from producer/creative-director]
+```
+
+---
+
+## Phase 4: Verdict
+
+Assign a canonical verdict based on net scope change:
+
+| Net Change | Verdict | Meaning |
+|-----------|---------|---------|
+| ≤10% | **PASS** | On Track — within acceptable variance |
+| 10–25% | **CONCERNS** | Minor Creep — manageable with targeted cuts |
+| 25–50% | **FAIL** | Significant Creep — must cut or formally extend timeline |
+| >50% | **FAIL** | Out of Control — stop, re-plan, escalate to producer |
+
+Output the verdict prominently:
+
+```
+**Scope Verdict: [PASS / CONCERNS / FAIL]**
+Net change: [+X%] — [On Track / Minor Creep / Significant Creep / Out of Control]
+```
+
+---
+
+## Phase 5: Next Steps
+
+After presenting the report, offer concrete follow-up:
+
+- **PASS** → no action required. Suggest re-running before next milestone.
+- **CONCERNS** → offer to identify the 2–3 additions with best cut ratio. Reference `/sprint-plan update` to formally re-scope.
+- **FAIL** → recommend escalating to producer. Reference `/sprint-plan update` for re-planning or `/estimate` to re-baseline timeline.
+
+Always end with:
+> "Run `/scope-check [name]` again after cuts are made to verify the verdict improves."
+
+---
 
 ### Rules
+
 - Scope creep is additions without corresponding cuts or timeline extensions
-- Not all additions are bad — some are discovered requirements. But they must be acknowledged and accounted for.
+- Not all additions are bad — some are discovered requirements. But they must be acknowledged and accounted for
 - When recommending cuts, prioritize preserving the core player experience over nice-to-haves
 - Always quantify scope changes — "it feels bigger" is not actionable, "+35% items" is

.claude/skills/sprint-status/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: sprint-status
-description: "Fast sprint status check. Reads the current sprint plan, scans story files for status, and produces a concise progress snapshot with burndown assessment and emerging risks. Run at any time during a sprint for quick situational awareness."
+description: "Fast sprint status check. Reads the current sprint plan, scans story files for status, and produces a concise progress snapshot with burndown assessment and emerging risks. Run at any time during a sprint for quick situational awareness. Use when user asks 'how is the sprint going', 'sprint update', 'show sprint progress'."
 argument-hint: "[sprint-number or blank for current]"
 user-invocable: true
 allowed-tools: Read, Glob, Grep
+context: fork
 ---
 
 # Sprint Status
@@ -20,6 +21,8 @@ files, and makes at most one concrete recommendation.
 
 ## 1. Find the Sprint
 
+**Argument:** `$ARGUMENTS[0]` (blank = use current sprint)
+
 - If an argument is given (e.g., `/sprint-status 3`), search
   `production/sprints/` for a file matching `sprint-03.md`, `sprint-3.md`,
   or similar. Report which file was found.

.claude/skills/story-readiness/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: story-readiness
-description: "Validate that a story file is implementation-ready. Checks for embedded GDD requirements, ADR references, engine notes, clear acceptance criteria, and no open design questions. Produces READY / NEEDS WORK / BLOCKED verdict with specific gaps."
+description: "Validate that a story file is implementation-ready. Checks for embedded GDD requirements, ADR references, engine notes, clear acceptance criteria, and no open design questions. Produces READY / NEEDS WORK / BLOCKED verdict with specific gaps. Use when user says 'is this story ready', 'can I start on this story', 'is story X ready to implement'."
 argument-hint: "[story-file-path or 'all' or 'sprint']"
 user-invocable: true
 allowed-tools: Read, Glob, Grep
@@ -23,6 +23,8 @@ gap list for each non-ready story.
 
 ## 1. Parse Arguments
 
+**Scope:** `$ARGUMENTS[0]` (blank = ask user via AskUserQuestion)
+
 - **Specific path** (e.g., `/story-readiness production/epics/combat/story-001-basic-attack.md`):
   validate that single story file.
 - **`sprint`**: read the current sprint plan from `production/sprints/` (most