Define the Podcast workflow

[alexeygrigorev]

Define the Podcast workflow

Status: pending
Tags: process-docs, work-engine, podcast, assistant, P0
Depends on: #4, #7 (baseline satisfied; #7 human Telegram smoke is not blocking this workflow-definition issue)
Blocks: #9, #44

Scope

Define the executable DataOps V1 Podcast workflow from the current DataTasks/Trello template, imported podcast SOPs/templates, and Podcast Assistant source state. This must be a workflow-first definition the operations manager can run from the DataOps work queue: tasks, reminders, follow-ups, required proof, docs-in-context, assistant artifacts, and operator actions must be explicit.

Use these source inputs:

• .goal-v1.md
• docs/operations-manager-platform-jtbd.md
• work-engine/docs/templates.md
• content/tasks/templates/podcast.md
• content/media/podcast/sops/
• content/media/podcast/templates/
• content/events/** and content/social-media/** podcast-related SOPs/templates where referenced by the workflow
• assistants/podcast/README.md
• assistants/podcast/process/podcast.md
• assistants/podcast/templates/podcast_guest_intake.md
• source-repo state from ../dtc-operations, ../datatasks, and ../podcast-assistant only for comparison; do not modify source repos

The deliverable should be the canonical Podcast workflow definition in the repo location used by the current workflow/template system, plus any focused validation fixtures or tests needed to prove it can be instantiated and operated. If #15 changes the final workflow-definition schema before this is implemented, use that schema. Otherwise, use the existing content/tasks/templates/podcast.md / work-engine template shape and document any fields that must be added later.

The workflow must cover the full lifecycle:

• guest intake and outreach
• date agreement and calendar setup
• podcast prep document creation and guest/Johanna collaboration
• event setup across Luma, Meetup, calendar, Airtable, website, Slack, LinkedIn, and X
• pre-event reminders
• live stream
• recording upload, edit, cover, transcript, playlists, timecodes, and YouTube description
• guest link follow-up
• Spotify, Apple Podcasts, Airtable, DTC podcast page, newsletter, and social follow-up
• archive and final closure

Acceptance Criteria

• The Podcast workflow has a clear trigger: manual creation when a guest agrees and a live stream date is confirmed, with the live stream date as the anchor date.
• The workflow defines bundle title variables, required bundle links/artifacts, stages, stage transitions, and done criteria for a Podcast episode.
• The existing Trello-derived 40-task reference and current 42-row git-backed template are reconciled into one canonical task list with stable task refs and an explicit note for any intentional additions, removals, or renamed tasks.
• Every task declares its phase, due offset, default owner/assignee where known, operator action, in-context instruction doc/template reference, and completion proof requirement.
• Completion proof is specific per task: required URL, required file, assistant artifact, comment/manual confirmation, or no proof required. Tasks with proof requirements cannot be marked done until proof is present.
• Required bundle links/artifacts include at least: guest email, podcast document, Luma, Meetup, YouTube stream/video, transcription, Spotify for Podcasters, public Spotify episode, Apple Podcasts episode, DTC podcast page, and any required Dropbox/banner/cover evidence surfaced by the SOPs.
• Waiting and follow-up semantics are defined for guest replies, date confirmation, missing bio/assets, missing event links, post-stream guest links, transcription/freelancer handoff, and publication links. Waiting work requires waitingFor, followUpAt, and a short note.
• Reminder semantics are defined for due, overdue, missing evidence, waiting follow-up, pre-event reminders at 7 days and 1 day before stream, and post-event follow-up tasks.
• At-risk workflow conditions are explicit, including missing podcast document, missing event pages, missing YouTube link, missing recording/transcription, missing public podcast links, and overdue/waiting follow-ups.
• Assistant integration is part of the workflow: raw guest/source material can produce a Podcast Assistant draft artifact attached to the workflow, the operator has a review/accept task, unresolved assistant TODOs become follow-up/waiting work, and the accepted artifact can satisfy the podcast-prep proof when linked or attached.
• Docs and templates are attached to tasks as contextual help rather than becoming the primary experience. Missing or weak SOP links are recorded as workflow TODOs but do not turn this into a docs-only issue.
• A sample Podcast bundle can be instantiated from the definition with correct due dates, required links/files, stage transitions, task refs, and bundle links/artifacts.
• The dashboard/workflow expectations for today, overdue, waiting, follow-ups due, missing evidence, and at-risk Podcast workflows are defined or validated against a sample bundle.
• Validation covers template parsing/seed behavior, sample bundle instantiation, proof blockers, waiting/follow-up state, reminder visibility, and stage transitions.

Test Scenarios

Scenario: Operator creates a Podcast workflow from a confirmed guest

Given: a guest has agreed to a podcast and the live stream date is set to 2026-08-17
When: the operator creates a Podcast workflow bundle from the definition
Then: the bundle is created with the expected title variables, required bundle links, stages, task refs, due dates relative to 2026-08-17, and docs-in-context links.

Scenario: Guest coordination becomes waiting work

Given: the operator has asked the guest for a bio, links, or date confirmation
When: the guest has not replied and the operator marks the task waiting
Then: the task requires waitingFor, followUpAt, and a note, stays visible as waiting work, and appears as follow-up due when followUpAt arrives.

Scenario: Missing proof blocks completion

Given: the operator tries to complete tasks such as create Luma event, create podcast document, complete actual stream, create transcript, or publish the DTC podcast page
When: the required link/file/artifact is missing
Then: completion is blocked with the missing evidence named, and the workflow is marked at risk until the evidence is added.

Scenario: Assistant draft becomes workflow evidence

Given: raw guest material is available for Podcast Assistant processing
When: the assistant creates a podcast prep draft artifact
Then: the artifact is attached to the Podcast workflow, a review task exists for the operator, accepted output can satisfy the podcast prep evidence, and unresolved TODOs are represented as follow-up or waiting work.

Scenario: Event and post-event stages advance correctly

Given: the event has been announced, the live stream happens, and post-event publishing work begins
When: milestone tasks are completed with required proof
Then: the workflow stage advances from preparation to announced to after-event to done, and cannot reach done while required publication links, archive evidence, or follow-up tasks remain incomplete.

Scenario: Podcast workflow appears correctly in daily operations views

Given: a Podcast workflow has overdue tasks, waiting guest work, and missing evidence
When: the operator opens the DataOps dashboard or workflow detail
Then: today, overdue, waiting, follow-up due, missing evidence, and at-risk states are visible without opening a docs folder first.

Out of Scope

• Building the full Podcast end-to-end portal slice; that belongs to Build the Podcast end-to-end slice #9.
• Building the Podcast Assistant portal UI spec; that belongs to Implement Podcast Assistant portal UI in workflow context #44.
• Importing or relocating Podcast Assistant source; that belongs to Import Podcast Assistant into assistants/podcast #7.
• Importing or reworking the Work Engine baseline; that belongs to Import DataTasks into work-engine #4.
• Designing the entire generic workflow data model unless needed to express this concrete Podcast workflow; coordinate with Define the first workflow data model #15 instead.
• Implementing Telegram, transcription, LLM, Slack, Luma, Meetup, YouTube, Spotify, Apple Podcasts, Airtable, Mailchimp, Dropbox, LinkedIn, or X integrations.
• Migrating active Trello cards or spreadsheet TODOs into runtime state.
• Rewriting all podcast SOP prose or filling every SOP placeholder. This issue may identify missing docs, but the main deliverable is the executable workflow definition.
• Modifying ../dtc-operations, ../datatasks, or ../podcast-assistant.

Dependencies

• Import DataTasks into work-engine #4 has provided the imported work-engine/ baseline and existing template/instantiation behavior this workflow builds on.
• Import Podcast Assistant into assistants/podcast #7 has provided the canonical assistants/podcast/ baseline needed to name and link assistant artifacts from this workflow definition. The remaining Import Podcast Assistant into assistants/podcast #7 human Telegram smoke verifies live external delivery and does not block Define the Podcast workflow #8.
• Build the Podcast end-to-end slice #9 should not start until this workflow definition is accepted, because Build the Podcast end-to-end slice #9 needs the workflow contract for the end-to-end slice.
• Implement Podcast Assistant portal UI in workflow context #44 should use this workflow definition as its source for assistant UI states, review actions, and artifact handoff.
• Define the first workflow data model #15, Define artifact model and storage policy #29, and Implement assistant job model and lifecycle #30 may refine the generic schema for workflows, artifacts, and assistant jobs. If those issues are completed first, this workflow should use their schema; if not, this issue should preserve the Podcast semantics in a forward-compatible structured definition.

[alexeygrigorev]

PM dependency triage for #8

Decision: #8 can proceed now.

#4 is closed and provides the imported work-engine baseline. #7 remains open with the human label, but the open item is only the [HUMAN] Telegram smoke using real external credentials. The #7 implementation has already passed Tester re-review, Assistant Engineer re-review, PM acceptance, commit/push, and on-call. Its accepted product baseline is the canonical assistants/podcast/ module and source boundary, which is sufficient for #8 to define the Podcast workflow and reference assistant artifacts.

I updated this issue from Status: blocked on #4 and #7 to Status: pending, clarified that #7's human Telegram smoke does not block this workflow-definition issue, and replaced the old root podcast-assistant/... source-input paths with canonical assistants/podcast/... paths.

Remaining caution: #8 should not require live Telegram/Groq/Heru execution. If implementation needs live assistant processing, that should stay human-gated or move to the assistant job/artifact follow-up work.

[alexeygrigorev]

READY FOR TEST

Implemented the canonical Podcast workflow definition using the current V1 workflow model from #15.

Changed files:

• work-engine/scripts/seed-templates.ts
• work-engine/tests/seed.test.ts
• content/tasks/templates/podcast.md
• work-engine/docs/templates.md

What changed:

• Kept the existing 42 stable Podcast task refs and enriched them into an executable workflow-first seed definition.
• Added Podcast phases/stages, source doc IDs, canonical required bundle links, default owner inheritance, task phase/system/doc context, per-task proof requirements, waiting/follow-up semantics, reminder semantics, at-risk conditions, dashboard state expectations, and assistant artifact/job refs.
• Documented the 40-task Trello reference versus the canonical 42-row DataOps workflow and the intentional additions.
• Added a human-readable workflow definition, assistant handoff, reminder/risk semantics, task execution matrix, and sample instantiation notes to content/tasks/templates/podcast.md.
• Added sample instantiation validation for anchor date 2026-08-17, including due dates, proof metadata, waiting semantics, assistant artifact/job refs, required publication links, and stage transitions.
• Did not build portal UI, external integrations, live assistant execution, or modify source repos.

Verification passed:

• git diff --check
• NODE_ENV=test SKIP_AUTH=true node --import tsx --test tests/seed.test.ts from work-engine/: 19 passed
• npm --prefix work-engine test: 627 passed
• npm --prefix work-engine run typecheck
• npm --prefix work-engine run build
• cd lambda-functions && uv run --extra search python -m lambda_functions.build_search_index --docs-dir ../content --output ../.tmp/dataops-content-search.index: indexed 357 documents
• uv run --project lambda-functions --extra search --with pytest python -m pytest tests/docs_app/test_backend_docs_metadata.py: 15 passed

Initial seed test run exposed undefined values inside DynamoDB validation payloads; I fixed that by omitting absent waiting semantics before the final passing runs.

No commit or push.

[alexeygrigorev]

TEST PASS

I verified the current uncommitted #8 diff only changes:

• work-engine/scripts/seed-templates.ts
• work-engine/tests/seed.test.ts
• content/tasks/templates/podcast.md
• work-engine/docs/templates.md

Commands run:

• git diff --check - passed.
• NODE_ENV=test SKIP_AUTH=true node --import tsx --test tests/seed.test.ts from work-engine/ - 19 passed, 0 failed.
• npm --prefix work-engine test - 627 passed, 0 failed.
• npm --prefix work-engine run typecheck - passed.
• npm --prefix work-engine run build - passed.
• cd lambda-functions && uv run --extra search python -m lambda_functions.build_search_index --docs-dir ../content --output ../.tmp/dataops-content-search.index - indexed 357 documents.
• uv run --project lambda-functions --extra search --with pytest python -m pytest tests/docs_app/test_backend_docs_metadata.py - 15 passed.

Per-criterion evidence:

• Trigger and anchor date: content/tasks/templates/podcast.md defines manual creation after guest agreement with live stream date as anchor; seed keeps triggerType: 'manual'; seed test asserts manual trigger and sample anchor date 2026-08-17.
• Bundle title variables, required links/artifacts, stages, transitions, done criteria: docs define date, topic, speaker, required bundle links, phase/stage mapping, and done criteria; seed defines PODCAST_PHASES, PODCAST_REQUIRED_BUNDLE_LINKS, stageOnComplete for actual-stream and final social task; tests assert phases, required links, and stage transitions on sample tasks.
• 42-task reconciliation vs 40-task reference: work-engine/docs/templates.md keeps the Trello-derived 40-task reference and points to the canonical executable 42-task workflow; content/tasks/templates/podcast.md records the two intentional additions, and seed tests assert 42 Podcast tasks.
• Task refs, offsets, owners, actions, doc context, systems, proof: withPodcastTaskSemantics enriches all 42 tasks with phase, systems, operator action, doc context, proof requirements, and validation metadata; seed tests iterate over every Podcast task and require phase/systems/proof/validation/operator action/dashboard states/instructions.
• Completion proof blockers: Podcast tasks get specific proofRequirement, requiredLinkName, and requiresFile metadata. Full work-engine tests passed existing blocker coverage for required links, required files, required comments, artifact/external-status proof metadata, and malformed proof requirements.
• Required bundle links/artifacts: seed/docs include guest email, podcast document, Luma, Meetup, YouTube stream/video, transcription, Spotify for Podcasters, public Spotify episode, Apple Podcasts episode, DTC podcast page, Dropbox recording folder, and podcast banner/cover; seed test asserts these names.
• Waiting/follow-up semantics: PODCAST_WAITING_TASKS covers guest/contact/date/bio/assets/event links/post-stream links/transcription/publication/guest-share follow-ups; validation requires waitingFor, followUpAt, and comment; sample instantiation asserts agree-on-a-date waiting semantics.
• Reminder and risk semantics: docs define due/overdue/missing-evidence/waiting follow-up/pre-event/post-event semantics and at-risk conditions; seed validation adds reminderSemantics, atRiskWhen, and dashboard states to tasks; tests assert pre-event reminders.
• Assistant integration: seed references assistants/podcast/..., source doc assistant.podcast.process.podcast, assistant-job.podcast-prep-draft, and artifact.podcast-assistant-draft; docs define review/accept behavior and unresolved TODO handling; tests assert assistant job/artifact refs on create-podcast-document and instantiated sample task.
• Docs as contextual help: every Podcast task is required by test to have instructionsUrl or instructionDocId; docs remain contextual help and no live external integrations were introduced.
• Sample instantiation: seed test instantiates a Podcast bundle for 2026-08-17 and asserts 42 tasks, sample due dates, proof metadata, waiting semantics, assistant refs, required publication links, and final done transition task.
• Dashboard expectations: docs and per-task validation define today, overdue, waiting, follow-up-due, missing-evidence, and at-risk; seed tests assert dashboard state metadata exists on every Podcast task.
• Validation coverage: focused seed tests cover parsing/seed behavior and sample instantiation; full work-engine tests cover proof blockers, waiting state, reminder/follow-up notifications, stage transitions, template API validation, and portable export validation.

Screenshots: not applicable; no UI changed.

No files were edited, committed, pushed, or closed by this Tester pass.