Add effects & skills audit report (Step 5)

docs/task3/effects_audit_report.md

@@ -0,0 +1,157 @@
+# Effects & Skills Audit Report - Mana Loop Game
+
+**Date:** 2025-01-26  
+**Auditor:** Senior Next.js Developer / Game Logic Reviewer  
+**Scope:** Effects (`effects.ts`, `upgrade-effects.ts`), Skills (`constants/skills.ts`, `skill-evolution.ts`), Enchantments (`data/enchantments/`), Implementation (`store.ts`, `crafting-slice.ts`)
+
+---
+
+## 1. Visual Inconsistencies (for effects/skills UI)
+
+### 1.1 Missing Visual Feedback for Skill Upgrade Effects
+
+| Issue | Location | Details |
+|-------|----------|---------|
+| No visual indicator for active special effects | SkillsTab, StatsTab | Players can't see which special effects are active (e.g., `manaCascade`, `eternalFlow`). Only the perk name is shown, not the dynamic effect state |
+| Missing upgrade tier indicators | SkillsTab | No visual distinction between Tier 1-5 skills in the UI. The evolution system has 5 tiers but UI doesn't reflect this |
+| Per-mana-type capacity upgrades not shown clearly | SkillsTab, StatsTab | New per-mana-type skills (fireManaCap, waterManaCap, etc.) from Bug 9 are in the "mana" category but may not show which specific element types have been upgraded |
+
+### 1.2 Inconsistent Effect Display
+
+| Issue | Location | Details |
+|-------|----------|---------|
+| Enchantment effect power not displayed | EquipmentTab | The `enchantPower` multiplier from skills (Essence Refining, Enchanting perks) is never shown to the player |
+| Element capacity breakdown missing | StatsTab | While Bug 14 added mana breakdown, it may not show the per-type capacity bonuses from new skills |
+
+---
+
+## 2. UX Friction Points (for skill/enchantment interactions)
+
+### 2.1 Skill Study Cost Confusion
+
+| Issue | Location | Impact |
+|-------|----------|--------|
+| Per-mana-type skills require element mana to study (Bug 9, 11) but this isn't clearly communicated | SkillsTab | Players may not understand why they need Fire mana to study "Fire Mana Capacity +10%" |
+| Effect Research skills cost both Transference + element mana (Bug 11) but UI may not show both costs | SkillsTab | The `cost` field in SKILLS_DEF includes `type: 'element'` but only shows one element type, not both Transference + element |
+
+### 2.2 Enchantment Design Flow Issues
+
+| Issue | Location | Details |
+|-------|----------|---------|
+| `enchantPower` multiplier never applied to enchantment effects | `effects.ts:computeEquipmentEffects()`, `upgrade-effects.ts:computeEffects()` | **CRITICAL**: The `enchantPower` stat (from Essence Refining skill and Enchanting perks) is defined but NEVER applied in any computation. Enchantment effects are calculated without this multiplier. |
+| No feedback when `essenceRefining` should apply | Entire enchantment system | The Essence Refining skill (max: 1, +10% enchantment effect power) is defined in `constants/skills.ts:35` but the effect never triggers because `enchantPower` isn't used |
+
+### 2.3 Dead Code / Never-Triggered Logic
+
+| Issue | Location | Details |
+|-------|----------|---------|
+| `enchantPower` stat never read | `upgrade-effects.ts`, `effects.ts` | The stat `enchantPower` appears in 20+ perk definitions in `skill-evolution.ts` but is never read by `computeEffects()` or `computeEquipmentEffects()` |
+| `essenceRefining` skill has no effect | `constants/skills.ts:35` | Even if studied, the +10% enchantment effect power is never applied since `enchantPower` isn't implemented |
+| `elemAttune` references in compute functions | `store.ts:340`, `utils/mana-utils.ts:30`, `store/computed.ts:51` | The legacy `elemAttune` skill is still referenced but the new per-mana-type skills (fireManaCap, etc.) from Bug 9 should be what's used |
+
+---
+
+## 3. Missing Feedback / Empty States (for skill/enchantment results)
+
+### 3.1 Missing Validation Feedback
+
+| Issue | Location | Issue |
+|-----------|----------|-------|
+| No validation that per-mana-type capacity upgrades actually work | `store.ts`, `utils/mana-utils.ts` | Need to verify the new skills (fireManaCap, etc.) are properly increasing element capacity. The `computeElementMax` function still uses `state.skills.elemAttune` instead of checking per-type skills |
+| No feedback when enchantment effect power bonus applies | Enchantment design/apply flow | Player doesn't know if their Essence Refining or Enchanting perks are affecting their enchantments |
+
+### 3.2 Missing Empty/Error States
+
+| Issue | Location | Issue |
+|-----------|----------|-------|
+| No error message when trying to study per-mana-type skill without required element mana | SkillsTab, `store.ts:startStudying()` | The game silently fails or shows generic "Not enough raw mana" message instead of specific element mana requirement |
+| No feedback when trying to apply enchantment that costs more capacity than available | `crafting-slice.ts:startApplying()` | Just returns `false` without explaining why |
+
+---
+
+## 4. Suggested Improvements (with priority: high / medium / low)
+
+### HIGH Priority
+
+| ID | Improvement | Components Affected | Rationale |
+|----|--------------|---------------------|-----------|
+| H1 | **Implement `enchantPower` multiplier in enchantment calculations** | `effects.ts:computeEquipmentEffects()`, `upgrade-effects.ts:computeEffects()` | **CRITICAL BUG**: The `enchantPower` stat is defined in 20+ skill perks but NEVER applied. Need to: (1) Add `enchantPowerMultiplier` to `ComputedEffects` and `UnifiedEffects`, (2) Apply it in `computeEquipmentEffects()` when calculating enchantment effect values, (3) Ensure Essence Refining skill (+10%) and Enchanting perks actually work |
+| H2 | **Fix `computeElementMax` to use per-mana-type skills (Bug 9)** | `store.ts:computeElementMax()`, `utils/mana-utils.ts:computeElementMax()`, `store/computed.ts` | The function still uses `state.skills.elemAttune` but should check individual per-mana-type skills (fireManaCap, waterManaCap, etc.) and apply their bonuses to the respective element's max capacity |
+| H3 | **Verify enchantment effect application uses unified effects** | `effects.ts`, `crafting-slice.ts` | Ensure `computeAllEffects()` (which merges skill upgrades + equipment effects) is used everywhere, not just `computeEquipmentEffects()` or `computeEffects()` separately |
+
+### MEDIUM Priority
+
+| ID | Improvement | Components Affected | Rationale |
+|----|--------------|---------------------|-----------|
+| M1 | **Add visual indicators for active special effects** | SkillsTab, StatsTab | Show which special effects are active (e.g., "Mana Cascade: +0.1 regen per 100 max mana") with tooltip explanations |
+| M2 | **Display per-mana-type capacity upgrades in UI** | SkillsTab, StatsTab | Show which element types have capacity bonuses and their values. The new skills (fireManaCap, etc.) need clear UI representation |
+| M3 | **Fix `elemAttune` legacy code references** | `store.ts`, `utils/mana-utils.ts`, `store/computed.ts` | Remove or deprecated references to `elemAttune` skill since per-mana-type skills (Bug 9) should handle this now. Or ensure backward compatibility |
+| M4 | **Add validation feedback for element mana costs** | SkillsTab, `store.ts:startStudying()` | When studying skills that require element mana (Bug 9, 11), show clear error messages about which element mana is needed and how much |
+| M5 | **Add `enchantPower` display to Enchantment UI** | EquipmentTab, Enchantment design/apply flow | Show player their current enchantment power multiplier from skills so they know the bonus is applying |
+
+### LOW Priority
+
+| ID | Improvement | Components Affected | Rationale |
+|----|--------------|---------------------|-----------|
+| L1 | **Clean up dead code (unused effect stats)** | `skill-evolution.ts`, `upgrade-effects.ts` | Remove or mark as deprecated the `enchantPower` stat if not being used, or add a TODO comment explaining the implementation plan |
+| L2 | **Add unit tests for per-mana-type capacity** | `skills.test.ts`, `store.test.ts` | Add tests verifying fireManaCap, waterManaCap, etc. properly increase the respective element's max capacity |
+| L3 | **Add unit tests for `enchantPower` when implemented** | `upgrade-effects.test.ts` | Once H1 is fixed, add tests verifying enchantment effects are properly multiplied |
+| L4 | **Standardize effect stat naming** | `upgrade-effects.ts`, `effects.ts` | Some stats use abbreviations (`regen`) while others use full names (`maxMana`). Consider standardizing |
+
+---
+
+## Summary of Critical Findings
+
+### Broken Logic (Doesn't Work as Intended)
+
+1. **`enchantPower` multiplier is NEVER applied** (H1)
+   - **Files**: `skill-evolution.ts` (defines perks with `stat: 'enchantPower'`), but `upgrade-effects.ts:computeEffects()` doesn't have a case for `enchantPower`
+   - **Impact**: Essence Refining skill (+10% enchantment effect power) and all Enchanting tier perks that give `enchantPower` are completely useless
+   - **Fix**: Add `enchantPowerMultiplier` to `ComputedEffects`, apply it in `computeEquipmentEffects()` when calculating final enchantment effect values
+
+2. **`computeElementMax` uses legacy `elemAttune` instead of new per-mana-type skills** (H2)
+   - **Files**: `store.ts:340`, `utils/mana-utils.ts:30`, `store/computed.ts:51-52`
+   - **Code**: `const base = 10 + (state.skills.elemAttune || 0) * 50 + ...`
+   - **Issue**: The new per-mana-type skills (fireManaCap, waterManaCap, etc.) from Bug 9 are defined but `computeElementMax` doesn't check them
+   - **Fix**: Either (a) make the per-mana-type skills modify `elemAttune` equivalent, or (b) rewrite `computeElementMax` to sum up per-type bonuses
+
+### Incomplete Implementation
+
+3. **Per-mana-type capacity upgrades (Bug 9) may not be integrated**
+   - **Files**: `constants/skills.ts:8-21` (defines skills), but no code applies these to element max capacity
+   - **Need to verify**: Whether the skills actually work or if they're just defined but never applied
+
+4. **`essenceRefining` skill has no effect** (related to #1)
+   - **File**: `constants/skills.ts:35`
+   - **Issue**: Skill can be studied, but +10% enchantment effect power is never applied
+
+### Dead Code (Never Triggers)
+
+5. **`enchantPower` stat is defined but never read**
+   - **Files**: `skill-evolution.ts` lines 794, 802, 817, 825, 840, 863, 871, 886, 916, 924, 939, 947, 962, 992, 1000, 1015, 1023, 1038, 1582, 1590
+   - **All these perks define `stat: 'enchantPower'` but nothing reads it**
+
+6. **`elemAttune` skill evolution path still exists but may be obsolete**
+   - **File**: `skill-evolution.ts:1945-` (SKILL_EVOLUTION_PATHS.elemAttune)
+   - **Issue**: With per-mana-type skills (Bug 9), the generic `elemAttune` may be obsolete, but the evolution path still exists
+
+---
+
+## Files Requiring Updates (Priority Order)
+
+1. **H1**: Implement `enchantPower` in `upgrade-effects.ts` and `effects.ts`
+2. **H2**: Fix `computeElementMax` in `store.ts`, `utils/mana-utils.ts`, `store/computed.ts`
+3. **H3**: Verify unified effects usage in `crafting-slice.ts`
+4. **M1**: Add special effects display to SkillsTab/StatsTab
+5. **M2**: Display per-mana-type upgrades in UI
+6. **M3**: Clean up `elemAttune` legacy references
+7. **M4**: Add validation feedback for element mana costs
+
+---
+
+## Notes
+
+- The `enchantPower` issue is the most critical finding - it means the Essence Refining investigation (Bug 15) was partially correct in identifying issues, but the root cause is that `enchantPower` stat is never applied anywhere
+- The per-mana-type capacity upgrades (Bug 9) need verification that they actually work - the skills are defined but may not be integrated into `computeElementMax`
+- The `elemAttune` skill evolution path in `skill-evolution.ts` may need to be updated or removed since per-mana-type skills replace its functionality
+- Consider adding debug logging or a "Effects Debug" panel to verify which effects are active and their values

docs/task3/todo.md

@@ -26,7 +26,7 @@
 - [x] Step 2: Sub-tasks planned and documented
 - [x] Step 3: Sub-tasks executed
 - [x] Step 4: UI Audit completed
-- [ ] Step 5: Effects & Skills Audit completed
+- [x] Step 5: Effects & Skills Audit completed
 
 ---