ios-fix

name	ios-fix
description	Bug-fix and refactoring workflow for MacMagazine — root cause analysis, pattern-matching fix, regression verification. Use when fixing a crash or bug, resolving a GitHub issue, debugging unexpected behavior, refactoring, or when the user says "fix", "bug", "broken", "issue

iOS Bug Fix & Refactoring

Use this skill when:

• Fixing bugs or defects
• Refactoring existing code
• Optimizing performance
• Addressing tech debt

For new features use /ios-implement.

---

Workflow: 3 Steps

Step 1: Investigation (MANDATORY)

No guessing. Must identify root cause before fixing.

## Bug Investigation

### 1. What's Broken?
- Expected behavior: [What should happen]
- Actual behavior: [What's happening]
- Impact: [Who's affected]

### 2. Root Cause Analysis
- [ ] Read the affected files completely
- [ ] Trace the code path causing the issue
- [ ] Search for similar patterns elsewhere

**Root cause**: [WHY the bug exists, not just WHAT is broken]
**Reference**: [file:line]

### 3. Correct Pattern
Does similar code exist that handles this correctly?
- [ ] Found correct implementation at: [file:line]
- [ ] Identified differences from broken code

### 4. Fix Strategy
- [ ] Fix root cause (not symptom)
- [ ] Follow existing patterns
- [ ] No new tech debt introduced

### 5. Regression Risk
- [ ] Identified dependent code
- [ ] Plan to test: [what to verify]

Step 2: Fix Implementation

Rule	Why
Fix root cause	Prevents recurring bugs
Match existing patterns	Maintains consistency
No new tech debt	Keeps quality high
Follow DRY	Reduces future bugs
Use existing helpers	Prevents proliferation

MacMagazine-specific checks:

• Card rendering bug? Check CardContent, CardContentType, CardStyle, NewsCard dispatcher
• WebView bug? Check MMWebView → ManagedWebView → WebPage chain
• Search bug? Check both phases (local SwiftData + remote WordPress API classification)
• Podcast bug? Check PodcastPlayerManager state and PodcastMiniPlayerModifier
• Theme bug? Check ThemeColor tokens and dark/light mode resolution

Step 3: Verification

Run /ios-dod then verify:

## Bug Fix Verification

### Investigation
- [x] Root cause identified (not guessed)
- [x] Correct pattern found in existing code

### Fix Quality
- [x] Fixes root cause (not symptom)
- [x] Follows existing patterns
- [x] No new tech debt

### Testing
- [x] Tests added for bug scenario
- [x] All existing tests pass
- [x] Build succeeds, lint passes

---

Common MacMagazine Bug Patterns

Search results showing wrong card type

Root cause: SearchResultsList not using the right card view per content type. Fix: News → NewsCard, Podcast → AdaptivePodcastCardView, Video → GlassCardView

Remote search missing podcasts/videos

Root cause: WordPress results not classified by podcastURL and category. Fix: Check RemoteFeedSearchService classification logic and FeedViewModel.searchAll()

WebView horizontal scroll on small content

Root cause: Missing scroll behavior modifier. Fix: .scrollBounceBehavior(.basedOnSize, axes: .horizontal) on the WebView

Theme colors wrong in dark mode

Root cause: Using hardcoded colors instead of theme tokens. Fix: Use @Environment(\.theme) and theme.main.background.color

---

Enforcement

FAIL Conditions

• Skip investigation and guess at fix
• Patch symptom instead of root cause
• Create new patterns instead of following existing
• Skip tests for bug scenario

SUCCESS Conditions

• Root cause identified with evidence
• Fix follows existing patterns
• Tests cover the bug scenario
• No regressions introduced