Mana-Loop/docs/strategy/overall-remediation-plan.md

# Mana Loop — Remediation & Redesign Strategy

**Document Status:** Working Draft  
**Purpose:** Systematic plan to stabilise the game, redesign broken systems, and deliver a genuinely good product.

---

## The Current State

The codebase arrived in a state where several systems need attention:

1. **The skill system is incoherent** — it evolved without a clear design philosophy and the attunement pivot was never cleanly landed.
2. **The UI is visually unacceptable** — generic AI-generated aesthetics, not a designed game.

These problems require focused solutions. This document covers all of them in a prioritised, structured way.

---

## Part 1 — Skill System Redesign

### Philosophy: Trash and Restart

The existing system has 15 skill evolution modules, 5 tiers with 10,000x scaling, milestone upgrade trees, hybrid skills, and research unlocks. It grew organically and now no one — including the AI agent — can reliably predict what a skill change does.

The new system has one guiding principle: **every skill is just a collection of named effects, and every effect has a single number that says how much it changes.**

---

### New Skill Architecture

#### Concept: Skills as Effect Bundles

```typescript
// Every skill is just metadata + an array of effects
interface SkillDef {
  id: string;
  name: string;
  description: string;
  category: SkillCategory;
  attunementRequired?: string;   // Which attunement unlocks this
  maxLevel: number;              // Usually 10
  studyCost: (level: number) => number;
  studyTime: (level: number) => number;   // hours
  effects: SkillEffect[];        // Applied at level 1, scale linearly
}

// An effect is a single stat change
interface SkillEffect {
  stat: StatKey;           // e.g. 'maxMana', 'regenRate', 'damageMultiplier'
  mode: 'add' | 'multiply';
  valuePerLevel: number;   // e.g. 100 (add 100 per level) or 0.05 (add 5% per level)
}

// The full set of game stats
type StatKey =
  | 'maxMana'
  | 'manaRegen'
  | 'clickMana'
  | 'elementCap'
  | 'studySpeed'
  | 'studyCostMult'
  | 'meditationMult'
  | 'enchantCapacity'
  | 'enchantSpeed'
  | 'enchantPower'
  | 'disenchantRecovery'
  | 'baseDamage'
  | 'damageMultiplier'
  | 'attackSpeed'
  | 'critChance'
  | 'critMultiplier'
  | 'armorPierce'
  | 'insightGain'
  | 'golemDamage'
  | 'golemDuration'
  | 'pactMultiplier'
  | 'conversionRate';
```

#### Concept: Milestone Choices (Simplified)

Keep milestone choices at level 5 — they're fun and create build identity. Simplify to 3 choices max:

```typescript
interface SkillMilestone {
  atLevel: number;          // 5 or 10
  choices: MilestoneChoice[];  // Always exactly 2-3 options
}

interface MilestoneChoice {
  id: string;
  label: string;
  description: string;
  effects: SkillEffect[];  // Same format as skill effects
}
```

No upgrade paths, no prerequisite trees within milestones. Choose once. Done.

#### Concept: Tiers as New Skills, Not Multipliers

Tiers-as-10,000x-multipliers is a design smell. It makes early choices feel irrelevant and creates absurd numbers. Instead:

**Tiering up unlocks a new skill in the same category, not a multiplied version of the old one.**

```
Mana Well (max 10)
  → Tier-up unlocks: "Deep Reservoir" skill (a genuinely different bonus)
  
Deep Reservoir (max 5)
  → Tier-up unlocks: "Mana Conduit" skill (yet another distinct ability)
```

Each tier-unlocked skill has its own effects, its own flavour. Power grows because you're stacking multiple skills, not because a single skill has a 10,000x internal multiplier.

---

### New Skill Categories

#### Core (No Attunement)

| Skill | Effect | Max |
|-------|--------|-----|
| Mana Well | +100 maxMana/level | 10 |
| Mana Flow | +1 manaRegen/level | 10 |
| Elemental Affinity | +50 elementCap/level | 10 |
| Quick Learner | +10% studySpeed/level | 10 |
| Focused Mind | -5% studyCost/level | 10 |
| Meditation Mastery | +15% meditationMult/level | 5 |

#### Enchanter Attunement

| Skill | Effect | Max | Requires |
|-------|--------|-----|---------|
| Enchanting | Unlocks 3-step enchant | 10 | Enchanter 1 |
| Efficient Enchant | -5% enchantCapacity cost/level | 5 | Enchanting 3 |
| Enchant Speed | -10% enchantSpeed/level | 5 | Enchanting 2 |
| Essence Refining | +10% enchantPower/level | 3 | Enchanting 5 |
| Disenchanting | +20% disenchantRecovery/level | 3 | Enchanting 2 |

#### Invoker Attunement

| Skill | Effect | Max | Requires |
|-------|--------|-----|---------|
| Pact Binding | +10% pactMultiplier/level | 10 | Invoker 1 |
| Invocation Mastery | +5% damageMultiplier/level | 10 | Invoker 2 |
| Guardian Lore | +20% damage vs guardians/level | 5 | Invoker 3 |
| Ritual Speed | -15% pact ritual time/level | 3 | Invoker 2 |

#### Fabricator Attunement

| Skill | Effect | Max | Requires |
|-------|--------|-----|---------|
| Golem Mastery | +10% golemDamage/level | 10 | Fabricator 2 |
| Golem Efficiency | +5% attackSpeed (golems)/level | 5 | Fabricator 2 |
| Golem Longevity | +1 golemDuration/level | 3 | Fabricator 3 |
| Crafting Mastery | -10% craft time/level | 5 | Fabricator 1 |

#### Attunement-Specific Research (Unlock Skills)

These are `max: 1` skills that unlock new capabilities. They don't need tiers or upgrade trees:

```typescript
// Flat unlock structure — no evolution needed
const RESEARCH_SKILLS: ResearchSkill[] = [
  { id: 'fireResearch',    unlocks: ['emberShot', 'fireball'],      req: { enchanting: 1 } },
  { id: 'waterResearch',   unlocks: ['waterJet', 'iceShard'],       req: { enchanting: 1 } },
  { id: 'lightningResearch', unlocks: ['spark', 'lightningBolt'],   req: { enchanting: 3 } },
  // ...
];
```

---

### Computed Stats: Single Source of Truth

All these skills feed into one `computeStats(state)` function that returns a flat `ComputedStats` object. Nothing reads from individual skill levels directly — everything reads from `ComputedStats`.

```typescript
function computeStats(state: GameState): ComputedStats {
  const stats: ComputedStats = { ...BASE_STATS };
  
  // Apply every skill level × its effects
  for (const [skillId, level] of Object.entries(state.skills)) {
    const def = SKILLS[skillId];
    if (!def || level === 0) continue;
    
    for (const effect of def.effects) {
      if (effect.mode === 'add') {
        stats[effect.stat] += effect.valuePerLevel * level;
      } else {
        stats[effect.stat] *= 1 + (effect.valuePerLevel * level);
      }
    }
  }
  
  // Apply milestone choices
  for (const choiceId of state.skillUpgrades) {
    const choice = MILESTONE_CHOICES[choiceId];
    if (!choice) continue;
    for (const effect of choice.effects) {
      // same logic
    }
  }
  
  // Apply equipment enchantments
  // Apply prestige upgrades
  
  return stats;
}
```

This is **testable by design**. Every skill test is: given skill X at level Y, `computeStats()` returns Z.

---

### Migration Plan

1. Write `computeStats()` with tests (TDD).
2. Define all skills in the new flat format in `constants/skills-v2.ts`.
3. Keep the old skill IDs — just change how they're computed. The existing `state.skills` shape doesn't change.
4. Delete `skill-evolution-modules/` entirely.
5. Delete `skill-evolution.ts`.
6. Update all callers of computed stats to use the new function.
7. Run all existing tests. Fix any that fail.

---

## Part 2 — Attunement Expansion

### Vision: Many Paths, Player Chooses

Current state: 3 attunements, all unlocked via linear progression.

Target state: **8–10 attunements** grouped into paths. Player picks one path at each milestone. Paths are:

- **Combat Path** — focus on raw damage, speed, and floor clearing
- **Crafting Path** — focus on enchantments, equipment power, and golemancy  
- **Utility Path** — focus on mana generation, study speed, and loop efficiency

---

### Attunement Redesign

#### The 3 Existing (Reworked)

| Attunement | Path | Slot | Primary Grant |
|------------|------|------|---------------|
| Enchanter | Crafting | Right Hand | Transference mana + enchanting access |
| Invoker | Combat | Chest | Pact power + guardian damage |
| Fabricator | Crafting | Left Hand | Earth mana + golem access |

#### New Attunements (Phase 2 additions)

| Attunement | Path | Slot | Primary Grant | Unlock Condition |
|------------|------|------|---------------|-----------------|
| **Battle Mage** | Combat | Head | +damage, attackSpeed | Reach floor 20 |
| **Arcanist** | Utility | Back | +mana cap, conversion rate | Study 5 skills to max |
| **Sage** | Utility | Head | +study speed, insight gain | Complete 3 loops |
| **Runesmith** | Crafting | Left Leg | +enchant capacity, crafting speed | Enchant 5 items |
| **Warden** | Combat | Right Leg | +elemental resist, armor pierce | Sign 3 pacts |
| **Timeweaver** | Utility | Back | -incursion penalty, +loop bonuses | Survive incursion |

#### Path Selection Moment

At **first prestige** (loop completion), player is presented with their first **Path Choice**:

> "Your magic has matured. Choose how to develop it:"
>
> 🗡️ **Combat Path** — Unlock Battle Mage + Warden attunements first. Focus: raw power, floor clearing.  
> ✨ **Crafting Path** — Unlock Runesmith + Fabricator advanced tiers first. Focus: equipment domination.  
> 🔮 **Utility Path** — Unlock Sage + Arcanist attunements first. Focus: meta progression, loop efficiency.

This choice doesn't lock out the other attunements permanently — it determines **unlock order and starting bonuses**. By loop 5, most players will have all attunements. The path just shapes the early and mid game.

---

### Attunement State Structure

Keep the existing `AttunementState` shape. Add:

```typescript
interface AttunementState {
  id: string;
  active: boolean;
  level: number;
  experience: number;
  title?: string;
  // NEW:
  path?: 'combat' | 'crafting' | 'utility';  // For path-specific bonuses
  unlockedAt?: number;  // Loop number when this was unlocked
}
```

---

## Part 3 — Enchanting System (Stable)

### Keep the 3-Step Flow

The 3-step flow is well-designed. Here is what each step does, stated precisely:

**Step 1 — Design**
- Player selects a piece of owned equipment.
- Player picks effects from their **unlocked pool** (what they've researched).
- System previews: total capacity cost, time to enchant.
- Player confirms → `startDesign(gearInstanceId, selectedEffects[])` is called.
- Transitions to `currentAction: 'designing'`.
- On completion → transitions to `currentAction: 'meditate'`. Design is saved.

**Step 2 — Prepare**
- Player selects the piece of gear they want to prepare (the one they designed for).
- If gear already has enchantments → they are removed, mana is returned (scaled by Disenchanting skill).
- System shows mana cost for preparation.
- Player confirms → `startPreparation(gearInstanceId, designId)`.
- Transitions to `currentAction: 'preparing'`.
- On completion → transitions to `currentAction: 'meditate'`. Gear is marked "prepared".

**Step 3 — Apply**
- Player selects the prepared gear + matching design.
- System shows time cost, mana cost, XP gain.
- Player confirms → `startApplication(gearInstanceId, designId)`.
- Transitions to `currentAction: 'enchanting'`.
- On completion → enchantment applied, Enchanter XP gained, transitions to `currentAction: 'meditate'`.

---

### UI for Enchanting

The selection implementation must use the store as the single source of truth. Audit the `EnchantmentDesigner` component:

```typescript
// WRONG pattern — local state doesn't sync with store
const [selectedEffects, setSelectedEffects] = useState([]);
// ...
<EffectButton onClick={() => setSelectedEffects([...selectedEffects, effect])} />

// CORRECT pattern — store is the single source of truth
const selectedEffects = useCraftingStore(s => s.enchantmentDesignState.selectedEffects);
const toggleEffect = useCraftingStore(s => s.toggleEffectSelection);
// ...
<EffectButton onClick={() => toggleEffect(effect.id)} />
```

---

## Part 4 — Prestige System Rework

### Vision: Loop Memories + Path Bonuses

Instead of a generic idle-game upgrade shop, prestige is split into two parts:

#### Part A: Loop Memories (Keep)

The Memory system (preserving spells/skills between loops) is the best part of the prestige system. Keep it. Expand it slightly:

- **Memory Slots** persist across loops (deep memory prestige upgrade is fine).
- Memories can be: a skill level, a spell, a completed enchantment design, or an attunement XP chunk.
- Add "Memory Imprinting" — at loop end, player chooses which memories to keep.

#### Part B: Path Bonuses

Instead of one flat upgrade shop, give each **path** its own upgrade tree that unlocks when you commit to that path:

```
Combat Path Permanents:
  - Veteran's Edge: Start each loop at floor 5 instead of 1
  - Battle-Hardened: +10% pact multipliers carry forward
  - Guardian's Boon: Guardian XP from last loop carries forward 25%

Crafting Path Permanents:
  - Master Craftsman: 1 enchantment design persists across loops
  - Runework Memory: Enchanter XP carries forward 30%
  - Crafting Legacy: 1 crafted item persists per loop

Utility Path Permanents:
  - Eternal Scholar: +20% starting mana per loop
  - Time Mastery: Incursion starts 2 days later
  - Insight Cascade: +15% insight per loop permanently
```

#### Part C: Universal Upgrades (Minimal)

Keep a small set of universal upgrades that any path can buy. These are just QoL, not power:

- Extra memory slot (+insight cost)
- UI options (loop history, achievement display)
- Starting equipment quality (common → uncommon after loop 5)

---

## Part 5 — UI Redesign

### Design Direction: Dark Arcane Codex

The game is about a mage in a time loop. The UI should feel like **a wizard's spellbook interface** — dark, deliberate, with glowing mana colors and a sense of weight and history.

**NOT:** Material Design, rounded pastel cards, generic dashboards, or Bootstrap tables.

**YES:** Dark background, warm amber/teal accent colors tied to the mana system, monospaced numbers for game stats, subtle texture via border treatments, clear information hierarchy.

---

### Design System

Define these tokens in `globals.css` before writing any component:

```css
/* Mana Loop Design Tokens */
:root {
  /* Backgrounds */
  --bg-void: #0d0d0f;          /* Page background */
  --bg-panel: #141418;         /* Panel background */
  --bg-surface: #1c1c22;       /* Card/surface background */
  --bg-raised: #242430;        /* Elevated elements */
  
  /* Text */
  --text-primary: #e8e6dc;     /* Main content */
  --text-secondary: #9e9c90;   /* Labels, captions */
  --text-muted: #5e5c56;       /* Disabled, placeholder */
  
  /* Mana Colors (tie to game elements) */
  --mana-raw: #8b7fd4;         /* Raw mana — purple */
  --mana-fire: #e85d24;        /* Fire — orange-red */
  --mana-water: #2ea8c4;       /* Water — teal */
  --mana-air: #a8d4e8;         /* Air — pale blue */
  --mana-earth: #b07d3c;       /* Earth — amber-brown */
  --mana-light: #e8c84a;       /* Light — gold */
  --mana-dark: #7a4db0;        /* Dark — deep purple */
  --mana-death: #6e8a96;       /* Death — grey-blue */
  --mana-transference: #1abc9c;/* Transference — teal-green */
  
  /* Semantic */
  --color-success: #4caf7d;
  --color-warning: #e8a84a;
  --color-danger: #c44b3a;
  --color-info: var(--mana-raw);
  
  /* Borders */
  --border-subtle: rgba(255,255,255,0.06);
  --border-default: rgba(255,255,255,0.12);
  --border-accent: rgba(255,255,255,0.22);
  
  /* Typography */
  --font-display: 'Cinzel', serif;     /* Headings, tab names */
  --font-body: 'Source Serif 4', serif; /* Prose text, descriptions */
  --font-ui: 'JetBrains Mono', monospace; /* Stats, numbers, game values */
  
  /* Spacing */
  --radius-sm: 4px;
  --radius-md: 6px;
  --radius-lg: 10px;
}
```

**Font sourcing:** All available via Google Fonts. Add to `layout.tsx`:
```typescript
import { Cinzel, Source_Serif_4, JetBrains_Mono } from 'next/font/google';
```

---

### Component Guidelines

**Stats and numbers** → always `font-family: var(--font-ui)`. Numbers should look precise, not soft.

**Tab headers** → `font-family: var(--font-display)`, muted color normally, accent color when active. No underlines or pills — use a subtle left or bottom border.

**Descriptions and lore** → `font-family: var(--font-body)`. The game has narrative flavor; let descriptions read like a spellbook.

**Progress bars** → use the element colors. A mana bar is `--mana-raw`. A fire element bar is `--mana-fire`. The color is the information.

**Panels** → `--bg-panel` background with a `1px solid var(--border-subtle)` border. No drop shadows. Use spacing to create hierarchy, not shadows.

**Buttons** — Three variants:
```
Primary:   bg --bg-raised, border --border-accent, text --text-primary
Secondary: bg transparent, border --border-default, text --text-secondary
Danger:    bg transparent, border --color-danger, text --color-danger
```

**Never use:** shadcn default styles without overriding, `rounded-full` for non-pill elements, white backgrounds, blue link colors, or any stock Tailwind color like `bg-blue-500`.

---

### Layout Rework

The current layout has a LeftPanel + main tabbed area. Keep this structure but rework the visual language:

```
┌──────────────────────────────────────────────────────────────┐
│  MANA LOOP                          Day 12 / 30                │  ← Top bar: game title, time
├──────────┬───────────────────────────────────────────────────┤
│          │  [Skills] [Spire] [Crafting] [Equipment] [...]     │  ← Tab bar
│  STATUS  ├───────────────────────────────────────────────────┤
│  PANEL   │                                                    │
│          │     ACTIVE TAB CONTENT                             │
│  Mana    │                                                    │
│  Elements│                                                    │
│  Action  │                                                    │
│  Activity│                                                    │
│  Log     │                                                    │
└──────────┴───────────────────────────────────────────────────┘
```

Left panel content (from top):
1. Mana display (raw mana bar + current/max)
2. Elemental mana bars (only show unlocked elements)
3. Current action with progress bar
4. Attunement status strip
5. Activity log (scrollable, last 20 events)

---

### UI Implementation Order

1. `globals.css` — design tokens only. No component styles yet.
2. Left panel redesign (most-seen element).
3. Tab bar redesign.
4. Mana display component.
5. Skill tab (most complex, do last after skill system redesign).
6. Equipment tab.
7. Enchanting crafting tab.

Each component gets its own TASK.md. The agent must not redesign multiple components in one task.

---

## Execution Sequence

Work in this order. Do not start a phase until the previous phase's acceptance criteria are met.

```
Phase 0 ── E2E test coverage + validate existing systems
   │        DONE WHEN: enchanting flow, gear equipping, and combat all have passing E2E tests
   │        GATE: all E2E tests green, no regressions
   │
Phase 1 ── Skill system redesign (Part 1 above)
   │        DONE WHEN: computeStats() replaces all skill-evolution-modules/
   │        GATE: all unit tests pass, no regression in game behaviour
   │
Phase 2 ── Enchanting UI (Part 3 above)
   │        DONE WHEN: 3-step flow works with store as single source of truth
   │        GATE: enchanting E2E test passes
   │
Phase 3 ── UI design system (Part 5 above — tokens + left panel only)
   │        DONE WHEN: design tokens defined, left panel redesigned
   │        GATE: no functional regression
   │
Phase 4 ── Attunement expansion (Part 2 above)
   │        DONE WHEN: new attunements defined, path choice works at prestige
   │        GATE: attunement store tests pass
   │
Phase 5 ── Prestige rework (Part 4 above — path bonuses)
   │        DONE WHEN: path bonuses replace generic shop (or coexist cleanly)
   │        GATE: prestige store tests pass
   │
Phase 6 ── Full UI redesign (Part 5 above — all remaining tabs)
            DONE WHEN: all tabs use new design system
            GATE: visual review + E2E tests still pass
```

---

## E2E Test Plan (Playwright) — Priority Order

These tests validate that core gameplay loops work correctly and remain stable. Each test should be written **before** any related implementation work begins (TDD).

```typescript
// e2e/enchanting.spec.ts
test('can select enchantment effect from unlocked pool', async ({ page }) => {
  // Navigate to enchanting tab
  // Click an available effect
  // Assert it appears in the design panel with correct capacity cost
});

test('can complete full 3-step enchant flow', async ({ page }) => {
  // Design → Prepare → Apply
  // Assert enchantment is applied to the gear and Enchanter XP increased
});

test('cannot select locked enchantment effects', async ({ page }) => {
  // Assert unresearched effects are visually disabled / non-interactive
});

// e2e/equipment.spec.ts
test('equipping item updates the correct equipment slot', async ({ page }) => {
  // Pick up an item → click a slot → assert slot shows the item
});

test('2-handed weapon blocks offhand slot', async ({ page }) => {
  // Equip 2H weapon → assert offhand is greyed out / blocked
});

test('unequipping item returns it to inventory', async ({ page }) => {
  // Remove item from slot → assert it appears in inventory
});

// e2e/combat.spec.ts
test('spell cast progress advances over time during combat', async ({ page }) => {
  // Enter combat → wait → assert cast progress bar has advanced
});

test('enemy HP decreases on spell completion', async ({ page }) => {
  // Complete a spell cast → assert enemy HP is reduced by expected amount
});

test('defeating all enemies on a floor advances to next floor', async ({ page }) => {
  // Kill last enemy → assert floor counter increments and new enemies appear
});

test('death resets to correct floor on reincarnation', async ({ page }) => {
  // Die → reincarnate → assert floor reset matches prestige expectations
});
```

---

## Task Structure for the Agent

For each phase, create individual TASK.md files. Keep each task under 200 lines of code change. Example structure:

```
docs/tasks/
  TASK-001-playwright-setup.md
  TASK-002-enchanting-e2e-tests.md
  TASK-003-equipment-e2e-tests.md
  TASK-004-combat-e2e-tests.md
  TASK-005-globals-css-tokens.md
  TASK-006-left-panel-redesign.md
  ...
```

Each task file follows the TASK_TEMPLATE.md format. The agent receives ONE task at a time. After it's committed, you verify it, then send the next task.

**Prevent blast radius:** The "Files NOT to Touch" field in each task is critical. The combat tests should not touch the enchanting files. The UI redesign should not touch the store. Explicit constraints prevent the agent from "helpfully" refactoring adjacent code.

---

## Quick Reference: First 5 Tasks

If you're starting today, create these tasks in order:

1. **TASK-001-playwright-setup.md** — Add Playwright to the project, configure `playwright.config.ts`, establish baseline test runner.
2. **TASK-002-enchanting-e2e-tests.md** — Write E2E tests covering the 3-step enchant flow and effect selection. Must pass.
3. **TASK-003-equipment-e2e-tests.md** — Write E2E tests for gear equipping, 2H weapon slot blocking, and unequip-to-inventory. Must pass.
4. **TASK-004-combat-e2e-tests.md** — Write E2E tests for spell casting progression, enemy HP reduction, and floor advancement. Must pass.
5. **TASK-005-globals-css-tokens.md** — Define the design tokens in `globals.css`. No component styles yet.

Get those 5 done and you'll have validated gameplay with a solid test safety net and the foundation for the visual redesign. Everything else is iterative improvement.