iOS Background Task Scheduling Debugging Runbook Builder
Create an iOS background task debugging runbook for BGTaskScheduler, background fetch, silent push, permissions, app lifecycle, battery constraints, and release validation.
Prompt Template
You are a senior iOS engineer creating a debugging runbook for background task scheduling and execution. Build the runbook for: App context: [consumer app, health app, productivity app, messaging, fintech, logistics, media, offline sync] iOS targets: [iOS versions, iPadOS if relevant, SwiftUI/UIKit, app extensions] Background mechanisms: [BGAppRefreshTask, BGProcessingTask, silent push, background URLSession, Core Location, HealthKit, Bluetooth, legacy fetch] Expected behavior: [sync content, upload logs, refresh widgets, process queue, download media, send reminders] Symptoms: [task never runs, delayed, killed early, duplicate work, high battery, missing network, test works but production fails] Entitlements and config: [Info.plist identifiers, permitted background modes, capabilities, provisioning profiles] Scheduling code: [task identifiers, earliestBeginDate, expiration handler, reschedule location, async/await, operation queue] Server triggers: [silent push payloads, collapse IDs, priority, rate limits, user segmentation] Observability: [OSLog, MetricKit, analytics events, server timestamps, crash reports, device logs] Test devices: [simulator, physical devices, TestFlight, production, low power mode, locked screen] Privacy and safety constraints: [no sensitive payload logs, health/finance data, user consent, battery impact] Recent changes: [new release, entitlement change, push provider migration, battery complaint, OS update] Create: 1. Triage decision tree from symptom to entitlement, registration, scheduling, system policy, network, push, or task-code cause. 2. Configuration checklist for Info.plist, task identifiers, background modes, capabilities, provisioning, and launch registration. 3. Code review checklist for scheduling, rescheduling, expiration handlers, idempotency, and cancellation. 4. Silent push and server-trigger debugging checklist. 5. Local testing methods and their limits for simulator, LLDB, TestFlight, and production devices. 6. Observability plan with privacy-safe logs and metrics for scheduled, launched, completed, expired, failed, and rescheduled tasks. 7. Test matrix for app states, Low Power Mode, network, permissions, device lock, OS versions, and user settings. 8. Common failure modes with evidence, likely cause, and fix. 9. Release guardrails and regression checks before shipping. 10. Escalation packet for mobile, backend, QA, and support teams. Do not include secrets, device tokens, private user data, or unsupported claims about iOS scheduling guarantees. Mark Apple-policy details for official documentation verification.
Example Output
Triage Flow
1. Confirm the task identifier is registered at launch before scheduling.
2. Verify the identifier appears in permitted background task scheduler identifiers.
3. Check whether the app reschedules after completion and after expiration.
4. Compare scheduled timestamp, launch timestamp, completion result, and server work availability.
5. Reproduce on a physical device with Low Power Mode and locked-screen scenarios.
Metrics
| Metric | Why It Matters |
|---|---|
| scheduled_at to launched_at | Shows system delay by task type and device state |
| expiration_count | Reveals work that exceeds background time |
| duplicate_job_count | Catches non-idempotent rescheduling or retries |
Guardrail
Never promise exact run times. The runbook should explain that iOS schedules background work opportunistically based on system policy.
Tips for Best Results
- 💡Ask for the exact background mechanism; BGProcessing, silent push, and background URLSession fail in different ways.
- 💡Require physical-device testing because simulator shortcuts hide many scheduling constraints.
- 💡Make every background job idempotent before debugging timing problems.
Related Prompts
Mobile Push Notification Delivery Debugging Runbook Builder
Create a mobile push notification debugging runbook for APNs, FCM, device tokens, permissions, payloads, queues, delivery metrics, and escalation.
Code Review Assistant
Get a thorough, senior-level code review with actionable feedback on quality, security, performance, and best practices.
Debugging Detective
Systematically debug errors and unexpected behavior with root cause analysis and fix suggestions.