ios-apple-docs-research skill

---
name: apple-docs-research
description: Use when researching Apple frameworks, APIs, or WWDC sessions - provides techniques for retrieving full transcripts, code samples, and documentation using browser automation and sosumi.ai
skill_type: discipline
version: 1.0.0
---

# Apple Documentation Research

## When to Use This Skill

✅ **Use this skill when**:

- Researching Apple frameworks or APIs (WidgetKit, SwiftUI, etc.)
- Need full WWDC session transcripts with code samples
- Looking for Apple Developer documentation
- Want to extract code examples from WWDC presentations
- Building comprehensive skills based on Apple technologies

❌ **Do NOT use this skill for**:

- Third-party framework documentation
- General web research
- Questions already answered in existing skills
- Basic Swift language questions (use Swift documentation)

## Related Tools & Skills

- Use the Playwright browser tools (`mcp__playwright__*`) for interactive browsing
- Use `skill-creator` when creating or updating skills from Apple documentation

## Core Philosophy

> Apple Developer video pages contain full verbatim transcripts with timestamps and complete code samples. Browser snapshots make this content accessible without manual copying.

**Key insight**: Don't manually transcribe or copy code from WWDC videos. The transcripts are already on the page, fully timestamped and formatted.

## WWDC Session Transcripts via Browser Snapshot

### The Technique

Apple Developer video pages (`developer.apple.com/videos/play/wwdc20XX/XXXXX/`) contain complete transcripts that can be extracted with a browser snapshot.

#### Step-by-Step Process

1. **Navigate** using Playwright:

   ```
   Use mcp__playwright__browser_navigate with:
   - url: "https://developer.apple.com/videos/play/wwdc2025/278/"
   ```

2. **Capture** the transcript text:

   ```
   Use mcp__playwright__browser_snapshot to capture the page text
   ```

3. **Read** the transcript from the snapshot:
   - Full spoken content with timestamps (e.g., `[0:07]`, `[1:23]`)
   - Descriptions of code and API usage (spoken, not formatted)
   - Chapter markers and resource links

### What You Get

**✅ WWDC transcripts contain:**

- Full spoken content with timestamps (e.g., `[0:07]`, `[1:23]`)
- API names mentioned by speakers (e.g., `widgetRenderingMode`, `supportedMountingStyles`)
- Descriptions of what code does ("I'll add the widgetRenderingMode environment variable")
- Step-by-step explanations of implementations
- Chapter markers and resource links

**❌ WWDC transcripts do NOT contain:**

- Formatted Swift code blocks ready to copy-paste
- Complete implementations
- Structured code examples

**Critical Understanding**: Transcripts are **spoken word, not code**. You'll read sentences like "I'll add the widgetRenderingMode environment variable to my widget view" and need to **reconstruct the code yourself** from these descriptions.

### When Code Isn't Clear from Transcript

If the transcript's code descriptions aren't detailed enough, follow this fallback workflow:

1. **Check Resources Tab**
   - Navigate back to the WWDC session page
   - Click "Resources" tab
   - Look for "Download Sample Code" or "View on GitHub"
   - Download Xcode project with complete working implementation

2. **Use sosumi.ai for API Details**
   - Look up specific APIs mentioned in transcript
   - Example: Transcript says "widgetAccentedRenderingMode" → look up `sosumi.ai/documentation/swiftui/widgetaccentedrenderingmode`
   - Get exact signature, parameters, usage

3. **Jump to Timestamp in Video**
   - Use transcript timestamp to jump directly to code explanation in video
   - Example: Transcript says code at `[4:23]` → watch that specific 30-second segment
   - Faster than watching entire 45-minute session

4. **Combine Sources**
   - Transcript = conceptual understanding + workflow
   - Resources = complete code
   - sosumi.ai = API details
   - Result: Full picture without manually reconstructing everything

**Example transcript structure**:

```markdown
# Session Title - WWDC## - Videos - Apple Developer

## Chapters
- 0:00 - Introduction
- 1:23 - Key Topic 1

## Transcript
0:00
Speaker: Welcome to this session...

[timestamp]
Now I'll add the widgetAccentedRenderingMode modifier...
```

### Example Session

**WWDC 2025-278** "What's new in widgets":

- Navigate: `https://developer.apple.com/videos/play/wwdc2025/278/`
- Captured: `001-navigate.md`
- Contains: ~15 minutes of full transcript with API references and code concepts

## Apple Documentation via sosumi.ai

### Why sosumi.ai

Developer.apple.com documentation is HTML-heavy and difficult to parse. sosumi.ai provides the same content in clean markdown format.

### URL Pattern

**Instead of**:

```
https://developer.apple.com/documentation/widgetkit
```

**Use**:

```
https://sosumi.ai/documentation/widgetkit
```

### URL Pattern Rules

**Format**: `https://sosumi.ai/documentation/[framework]`

**Rules for framework name**:

1. **Lowercase** - Use lowercase even if framework is capitalized (SwiftUI → swiftui)
2. **No spaces** - Remove all spaces (Core Data → coredata)
3. **No hyphens** - Remove all hyphens (App Intents → appintents, NOT app-intents)
4. **Case-insensitive** - Both `SwiftUI` and `swiftui` work, but lowercase is recommended

**Common mistakes**:

- ❌ `app-intents` → ✅ `appintents`
- ❌ `core-data` → ✅ `coredata`
- ❌ `AVFoundation` → ✅ `avfoundation`

**Examples**:

| Framework Name | sosumi.ai URL |
|----------------|---------------|
| SwiftUI | `sosumi.ai/documentation/swiftui` |
| App Intents | `sosumi.ai/documentation/appintents` |
| Core Data | `sosumi.ai/documentation/coredata` |
| AVFoundation | `sosumi.ai/documentation/avfoundation` |
| UIKit | `sosumi.ai/documentation/uikit` |

### Using with WebFetch or Read Tools

```
WebFetch:
  url: https://sosumi.ai/documentation/widgetkit/widget
  prompt: "Extract information about Widget protocol"

Result: Clean markdown with API signatures, descriptions, examples
```

### Framework Examples

| Framework | sosumi.ai URL |
|-----------|---------------|
| WidgetKit | `https://sosumi.ai/documentation/widgetkit` |
| SwiftUI | `https://sosumi.ai/documentation/swiftui` |
| ActivityKit | `https://sosumi.ai/documentation/activitykit` |
| App Intents | `https://sosumi.ai/documentation/appintents` |
| Foundation | `https://sosumi.ai/documentation/foundation` |

## Common Research Workflows

### Workflow 1: New iOS Feature Research

**Goal**: Create a comprehensive skill for a new iOS 26 feature.

1. **Find WWDC sessions** — Search "WWDC 2025 [feature name]"
2. **Get transcripts** — Navigate with the browser tool to each session
3. **Read transcripts** — Extract key concepts, code patterns, gotchas
4. **Get API docs** — Use sosumi.ai for framework reference
5. **Cross-reference** — Verify code samples match documentation
6. **Create skill** — Combine transcript insights + API reference

**Time saved**: 3-4 hours vs. watching videos and manual transcription

### Workflow 2: API Deep Dive

**Goal**: Understand a specific API or protocol.

1. **sosumi.ai docs** — Get protocol/class definition
2. **WWDC sessions** — Search for sessions mentioning the API
3. **Code samples** — Extract from transcript code blocks
4. **Verify patterns** — Ensure examples match latest API

### Workflow 3: Multiple Sessions Research

**Goal**: Comprehensive coverage across multiple years (e.g., widgets evolution).

1. **Parallel navigation** — Use the browser tool to visit 3-6 sessions
2. **Read all transcripts** — Compare how APIs evolved
3. **Extract timeline** — iOS 14 → 17 → 18 → 26 changes
4. **Consolidate** — Create unified skill with version annotations

**Example**: Extensions & Widgets skill used 6 WWDC sessions (2023-2025)

## Anti-Patterns

### ❌ DON'T: Manual Video Watching

```
BAD:
1. Play WWDC video
2. Pause and take notes
3. Rewind to capture code
4. Type out examples manually

Result: 45 minutes per session
```

### ✅ DO: Browser Snapshot

```
GOOD:
1. Navigate with Playwright
2. Capture transcript with browser snapshot
3. Extract API names and patterns
4. Reference timestamps for context

Result: 5 minutes per session
```

### ❌ DON'T: Scrape developer.apple.com HTML

```
BAD:
Use WebFetch on developer.apple.com/documentation
Result: Complex HTML parsing required
```

### ✅ DO: Use sosumi.ai

```
GOOD:
Use WebFetch on sosumi.ai/documentation
Result: Clean markdown, instant access
```

## Troubleshooting

### Transcript Not Found in Snapshot

**Symptom**: Snapshot text doesn't include the transcript

**Solution**:

1. Confirm the page finished loading (wait 2-3 seconds)
2. Scroll to the transcript section, then capture another snapshot
3. Some sessions require expanding a "Transcript" section or tab

### Transcript Incomplete

**Symptom**: File exists but missing transcript

**Solution**:

1. Page may still be loading - wait 2-3 seconds
2. Try navigating again
3. Some sessions require scrolling to load full content

### sosumi.ai Returns Error

**Symptom**: 404 or invalid URL

**Solution**:

1. Verify framework name spelling
2. Check sosumi.ai format: `/documentation/[frameworkname]`
3. Fallback: Use developer.apple.com but expect HTML

## Verification Checklist

Before using captured content:

- ☐ Transcript includes timestamps
- ☐ Code samples are complete (not truncated)
- ☐ Speaker names and chapter markers present
- ☐ Multiple speakers properly attributed
- ☐ Code syntax highlighting preserved

## Related Resources

### Browser Integration

- **Playwright** - Browser control for interactive navigation
- **auto-capture** - Automatic `.md` file generation on navigation (if available)

### Apple Developer Resources

- **WWDC Videos** - <https://developer.apple.com/videos/>
- **Documentation** - <https://sosumi.ai/documentation/>
- **Sample Code** - <https://developer.apple.com/documentation/samplecode>

### Skill Development

- **skill-creator** - Structure and review skills built from Apple documentation

---

**Time Saved**: Using this technique saves 30-40 minutes per WWDC session vs. manual video watching and transcription. For comprehensive research spanning multiple sessions, savings compound to 3-4 hours per skill.