existential-birds/beagle / plugins/beagle-ios/skills/watchos-code-review
watchos-code-review
VerifiedReviews watchOS code for app lifecycle, complications (ClockKit/WidgetKit), WatchConnectivity, and performance constraints. Use when reviewing code with import WatchKit, WKExtension, WKApplicationDelegate, WCSession, or watchOS-specific patterns.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.3 KB |
| references/complications.md | markdown | 5.4 KB |
| references/connectivity.md | markdown | 5.1 KB |
| references/lifecycle.md | markdown | 5.2 KB |
| references/performance.md | markdown | 5.4 KB |
references/complications.md
View on GitHub# watchOS Complications
## Evolution
- **ClockKit**: Deprecated framework (watchOS 2-8)
- **WidgetKit**: Modern replacement (watchOS 9+)
- **watchOS 10**: Smart Stack with relevance-based prioritization
- **watchOS 11**: `RelevantContext` API for context-aware widgets
## Widget Families (WidgetKit)
| Family | Use Case | ClockKit Equivalent |
|--------|----------|---------------------|
| `accessoryRectangular` | Multiple lines, graphs | `graphicRectangular` |
| `accessoryCircular` | Gauges, progress | `graphicCircular` variants |
| `accessoryInline` | Single text line | `utilitarianSmallFlat` |
| `accessoryCorner` | Icon + curved label (watchOS only) | `utilitarianSmall` |
## Timeline Provider Types
### Static Widget
```swift
struct Provider: TimelineProvider {
func placeholder(in context: Context) -> SimpleEntry
func getSnapshot(in context: Context, completion: @escaping (SimpleEntry) -> ())
func getTimeline(in context: Context, completion: @escaping (Timeline<SimpleEntry>) -> ())
}
```
### Configurable Widget (AppIntents)
```swift
struct Provider: AppIntentTimelineProvider {
func placeholder(in context: Context) -> SimpleEntry
func snapshot(for configuration: ConfigIntent, in context: Context) async -> SimpleEntry
func timeline(for configuration: ConfigIntent, in context: Context) async -> Timeline<SimpleEntry>
func recommendations() -> [AppIntentRecommendation<ConfigIntent>]
}
```
## Smart Stack Relevance
```swift
struct SimpleEntry: TimelineEntry {
var date: Date
var event: Event?
var relevance: TimelineEntryRelevance? {
guard let event = event else {
return TimelineEntryRelevance(score: 0)
}
return TimelineEntryRelevance(
score: 10,
duration: event.endDate.timeIntervalSince(date)
)
}
}
```
## Critical Anti-Patterns
### 1. Exceeding Refresh Budget
```swift
// BAD: Called on every data change
func dataDidUpdate() {
WidgetCenter.shared.reloadTimelines(ofKind: "MyWidget")
}
// GOOD: Throttle reloads, use timeline entries
func getTimeline(...) {
var entries: [Entry] = []
for hourOffset in 0..<24 {
let date = Calendar.current.date(byAdding: .hour, value: hourOffset, to: Date())!
entries.append(Entry(date: date, data: predictedData(for: date)))
}
completion(Timeline(entries: entries, policy: .atEnd))
}
```
**Budget**: ~40-70 refreshes/day (~every 15-60 minutes)
### 2. Gaps in Timeline
```swift
// BAD: Only entries for events
func getTimeline(...) {
for event in events {
entries.append(Entry(date: event.startDate, event: event))
}
}
// GOOD: Entries for state changes
func getTimeline(...) {
entries.append(Entry(date: Date(), event: currentEvent))
for event in upcomingEvents {
entries.append(Entry(date: event.startDate, event: event))
entries.append(Entry(date: event.endDate, event: nil)) // End state
}
}
```
### 3. Expensive Operations in Placeholder
```swift
// BAD: Blocks UI
func placeholder(in context: Context) -> Entry {
let data = fetchLatestData() // Network call!
return Entry(date: Date(), data: data)
}
// GOOD: Return static data immediately
func placeholder(in context: Context) -> Entry {
return Entry(date: Date(), data: .placeholder)
}
```
### 4. AsyncImage in Widget
```swift
// BAD: Won't work
var body: some View {
AsyncImage(url: imageURL) // Widgets can't do async in view
}
// GOOD: Fetch in timeline provider
func getTimeline(...) {
let imageData = try? Data(contentsOf: imageURL)
let entry = Entry(date: Date(), imageData: imageData)
completion(Timeline(entries: [entry], policy: .atEnd))
}
```
### 5. Not Implementing Migration
```swift
// BAD: User complications become blank
class ComplicationController: NSObject, CLKComplicationDataSource {
// Missing: var widgetMigrator: CLKComplicationWidgetMigrator
}
// GOOD: Implement migration
extension ComplicationController: CLKComplicationWidgetMigrator {
func widgetConfiguration(
from descriptor: CLKComplicationDescriptor
) async -> CLKComplicationWidgetMigrationConfiguration? {
return CLKComplicationStaticWidgetMigrationConfiguration(
kind: "MyWidget",
extensionBundleIdentifier: "com.myapp.widget"
)
}
}
```
## Key Modifiers
| Modifier | Purpose |
|----------|---------|
| `.widgetAccentable()` | Mark for accent coloring |
| `.widgetLabel { }` | Curved text for corner/circular |
| `.containerBackground(for: .widget)` | Smart Stack background |
| `.privacySensitive()` | Redact in Always-On |
| `AccessoryWidgetBackground()` | Consistent backdrop |
## Always-On Display
```swift
var body: some View {
VStack {
Image(systemName: "heart.fill")
.widgetAccentable()
if isLuminanceReduced {
Text("\(value)")
.redacted(reason: .placeholder) // Hide sensitive
} else {
Text("\(value) BPM")
.privacySensitive()
}
}
}
```
## Review Questions
1. Is WidgetKit used instead of ClockKit (watchOS 9+)?
2. Does `placeholder()` return immediately without async work?
3. Does the timeline include future entries (not just current)?
4. Is `TimelineEntryRelevance` implemented for Smart Stack?
5. Is `.privacySensitive()` applied to sensitive content?
6. Is `@Environment(\.isLuminanceReduced)` checked for Always-On?
7. Are images pre-fetched (not using AsyncImage)?
8. Is ClockKit migration implemented if updating from older app?
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |