What problem does it solve? Work that runs outside the request/response cycle — document ingestion, MCP refresh, reports, scheduled jobs — often fails silently: tasks get garbage-collected, flows cannot see uncommitted rows, and exceptions vanish with nothing in the logs. This Skill guides you to the right execution mechanism and prevents those exact failure modes. ## Core Features & Use Cases - Mechanism Selection: A decision table for choosing between Prefect flows (durable, retryable, scheduled), spawn() / spawn_after_commit() from app/core/background.py (in-process handoffs), and inline execution. - Failure-Mode Prevention: Explains why bare asyncio.create_task drops work silently, why flows reading their own row need spawn_after_commit, and why CLI commands must call drain() before returning. - Flow Authoring Rules: Conventions for defining flows in app/worker/tasks/, dispatching from services, registering CronSchedule/IntervalSchedule deployments, and enforcing serializable args, idempotency, and cost recording on failure. - Use Case: An upload endpoint returns {"status": "processing"} but ingestion never runs. This Skill diagnoses it as the spawn-before-commit race and shows the spawn_after_commit fix. ## Quick Start Ask the agent to add a new scheduled background flow for report generation following the background-task conventions.
