chore: flesh out skills.md — domains, categories, XP, gates, mastery, epics

docs/game-design/skills.md

@@ -2,6 +2,8 @@
 
 Vision-level design for how characters grow. **Combat** uses **gigs** (swap roles for grouping clarity); **each gig levels on its own track** (**per-gig** progression). **Non-combat** uses **skills** (gathering, crafting, and similar loops). [Epic 2 — Classless progression](../decomposition/epics/epic_02_classless_progression.md) (E2.M1–M4) still describes **skill** XP machinery; **gig** XP/levels are **per gig**—decomposition should be revisited when this split hardens.
 
+**Document scope:** the sections below **Skills (non-combat)** are the skills design pass. **Gig** detail is **[gigs.md](gigs.md)**; **brainstorm-only** ideas live under [`brainstorm/`](brainstorm/README.md).
+
 ## Vocabulary
 
 From here on in game-design docs:
@@ -25,28 +27,104 @@ The **gig** artifact—**roles**, **hub swap**, **per-gig progression**, **main
 
 ## Skills (non-combat, classless)
 
-Everything **outside combat role resolution**—gathering, refining, crafting lines, non-combat tech, etc.—uses **skills**:
+Everything **outside combat role resolution** trains on **skills**. That includes gathering, refining, crafting, non-combat tech work, and other **world interactions** we choose to track as progression.
 
-- **Any character can train any skill** over time (subject to world gates: discovery, rep, licenses—those expand content, they are not “you picked the wrong gig”).
-- **Identity** for “what you do in the economy” is the **skill graph + reputation + gear**, not the gig you ran last night.
+### Pillars
+
+- **Any character can train any skill** over time (subject to **world gates**: discovery, rep, licenses—those **add** content, they are not “you picked the wrong class”).
+- **Economy identity** is the **skill graph + reputation + gear**, not which **gig** you had equipped last night.
 - **Long-term:** avoid dead-end grinds; slow or expensive is fine, “wrong choice forever” is not.
 
-### What counts as a skill
+### What is (and isn’t) a skill
 
-A **skill** is a persistent, leveled capability improved primarily by **doing the activity** (chop, refine, assemble, etc.). Supplementary sources (books, training) stay optional. Skills stay **data-defined** (stable IDs, categories, prerequisites).
+A **skill** is a **persistent, leveled** capability, **data-defined** (stable IDs, categories, optional prerequisites). Primary progression is **doing the activity** (gather, refine, assemble, hack a door in a skill-based encounter, etc.). **Books, trainers, or mission grants** can supplement XP—**optional** and should not replace “play the loop” as the main fantasy.
+
+**Not skills:** **gig** combat progression, **raw item stats** with no trained gate, and **one-off** quest flags (unless we explicitly model them as skills—**open**).
+
+### Skill domains (examples)
+
+Domains are **content-shaped**, not a locked taxonomy. Early vision includes:
+
+| Domain | Examples (illustrative) |
+|--------|-------------------------|
+| **Extraction** | Salvage, mining, harvesting, reclaiming scrap |
+| **Processing** | Refining, chemistry prep, material conversion |
+| **Fabrication** | Weaponsmith, armtech, synth-chem, cooking if we track it |
+| **Tech / intrusion** | Non-combat hacking, bypass, diagnostics—**combat-facing** net actions stay **gig** |
+| **Support craft** | Medtech fabrication, field repair kits, augment maintenance (**open** naming) |
+| **Social / street** | Negotiation, street doc *craft*, fences—**only if** we give them real loops and XP (**open**) |
+
+New skills land here as **design + data** demand; domains can **overlap** one skill in multiple tags for UI.
 
 ### Categories (families)
 
-Categories group skills for **UI and balance** (e.g. *Gathering*, *Craft*, *Tech*, *Social*). They are **not** gigs and do not replace them.
+**Categories** group skills for **UI, filters, and balance**—they are **not** gigs, **not** professions, and **not** hard caps on how many skills you can raise.
 
-### XP, failure, caps, pacing (skills)
+**Draft families** (can merge or rename):
 
-- **Server-authoritative** grants with structured sources (node, recipe, mission payout, …).
-- **Failure XP** (XP on a **failed attempt** at a skill action—e.g. burnt recipe—not **death penalty**): **per skill / per mechanic**; **open** globally, will depend on how each activity is built and what exploit surface it has.
-- **Caps:** **Soft** only—no hard “max level” by default. **Each level needs more XP than the last** (threshold tables or formula; **data-driven** per skill or policy).
-- **Runaway mitigation** beyond the curve: diminishing returns, context modifiers, or other knobs if telemetry demands.
-- **Gates** (recipes, rep, licenses) should **add** paths, not fake gigs.
-- **Pacing/catch-up** (E2.M4) applies across **skills**; **gig** pacing is **per-gig** (same or parallel engine—**open**).
+| Category | Rough scope |
+|----------|-------------|
+| **Gather** | Nodes, yields, field extraction |
+| **Process** | Refine, batch, intermediate goods |
+| **Make** | Finished goods, recipes, bench work |
+| **Tech** | Intrusion, electronics, rigging that isn’t a gig kit |
+| **Social** | If we skill it: negotiation, contracts UI hooks (**open**) |
+
+A skill may appear in **more than one** category for sorting; **canonical** category lives in data for balance.
+
+### XP, levels, curves
+
+- **Server-authoritative** XP and level resolution ([E2.M2](../decomposition/modules/E2_M2_XpAwardAndLevelEngine.md)).
+- **Primary source (agreed):** **do the activity**—gather, craft steps, skill-based mission objectives, etc.
+- **Secondary sources (open):** quests, dailies, books, training dummies—tuned so they **assist** without **replacing** loops.
+- **Structured grants:** skill id, amount, **source** (node id, recipe, quest key…) for telemetry and anti-exploit review.
+
+**Failure XP** (failed craft, failed hack attempt—not **death**): **per skill / per mechanic**; **open** until each activity’s rules exist ([Decisions log](#decisions-log)).
+
+**Caps (agreed):** **soft** curve only—**each level needs more XP** than the last; **data-driven** per skill or policy. **Runaway** mitigation: steeper curves, context modifiers, diminishing returns on repeat actions—**open** per skill.
+
+**Pacing / catch-up** ([E2.M4](../decomposition/modules/E2_M4_ProgressionPacingControls.md)): global or cohort knobs for ops; **gig** pacing stays separate ([gigs.md](gigs.md)).
+
+### Gates, discovery, prerequisites
+
+**UnlockRequirement**-style gates ([E2.M1](../decomposition/modules/E2_M1_SkillDefinitionRegistry.md)) should **widen** what you can do, not mimic a class pick:
+
+- **Recipes** and **facilities** tied to skill tier or world state.
+- **Faction rep** or **licenses** for restricted goods or zones.
+- **Discovery:** find a schematic, rescue a teacher, complete a gig-agnostic storyline.
+
+**Open:** how much is **available at level 1** vs **gated**; how **alt-friendly** discovery is.
+
+### Mastery and perks (skills)
+
+Beyond raw level, **mastery tracks** and **perks** ([E2.M3](../decomposition/modules/E2_M3_MasteryAndPerkUnlocks.md)) give **build texture** inside one skill (branch picks, efficiency, side effects). Same *idea* as gig expression, **different** system—no shared perk tree between gig and skill unless we deliberately link them (**open**).
+
+**Respec** for skill mastery—**open** (cost, partial reset).
+
+### Cross-skill synergies
+
+**Open:** explicit **bonuses** when skill A + B cross a threshold vs **pure fiction** (“you’re known as a rigger-smith”) with no math. Avoid mandatory cross-grinds unless the loop is fun.
+
+### Where skills meet the rest of the game
+
+| Area | Tie-in |
+|------|--------|
+| [Epic 2](../decomposition/epics/epic_02_classless_progression.md) | Registry, XP engine, mastery, pacing |
+| [Epic 3](../decomposition/epics/epic_03_crafting_economy.md) | Gather and craft **award** skill XP; items and recipes |
+| [Epic 7](../decomposition/epics/epic_07_quest_faction.md) | Quest rewards, rep gates, optional skill payouts |
+| [gigs.md](gigs.md) | **Craft** combat gear with **skills**; **equip** with **gigs**—[Seams](#seams-gigs--skills) |
+| [brainstorm/hack-bodyguard-missions.md](brainstorm/hack-bodyguard-missions.md) | **Skill** lane in a group instance (idea only) |
+
+### Open questions (skills-only)
+
+| Topic | Status |
+|-------|--------|
+| Full launch **skill list** and names | Open |
+| Social / negotiation as tracked skills | Open |
+| Failure XP defaults per activity type | Open |
+| Mastery respec rules | Open |
+| Cross-skill synergy math | Open |
+| Skill-based **combat-adjacent** actions (e.g. deployable) vs **gig** ability | Open |
 
 ## Seams (gigs ↔ skills)
 
@@ -61,7 +139,7 @@ Categories group skills for **UI and balance** (e.g. *Gathering*, *Craft*, *Tech
 ## Player-facing readability
 
 - **Combat:** UI shows **main gig**, **sub-gig**, levels/tracks, combat abilities, and **combat gear** the main gig can use (mismatched gear disabled or greyed). Consumable tooltips for **passive** amps can show **baseline vs. boosted** when **main or sub** matches the item’s gig hook.
-- **Non-combat / crafting:** **skill** list, XP sources, categories; crafting combat gear does **not** hide recipes behind gigs—only **skill**/recipe gates (optional UI hint if the product is unequippable for your current gig).
+- **Non-combat / crafting:** **skill** list, **category** filters, XP with **source** hints where helpful; **mastery** branches when E2.M3-style systems exist. Crafting combat gear uses **skill**/recipe gates only—not gigs (optional hint if you can’t equip the product on your current gig).
 - **Story:** journal or quest UI can separate **character / faction** threads from **gig** threads so players see which arc belongs to which gig.
 - Use **gig** / **skill** consistently in specs and tools; flavor text can vary.