Map Book of the Week workflow to process docs

[alexeygrigorev]

Map Book of the Week workflow to operator-ready process docs and executable task metadata

Status: pending
Tags: P1, process-docs, work-engine, docs
Depends on: None
Blocks: None

Scope

Map the Book of the Week operating workflow into the DataOps V1 workflow-first model so an operations manager can instantiate a Book of the Week run, see the next actions by date, open SOPs/templates in context, track follow-ups, and complete tasks only when required proof is present.

The implementation should update the executable template metadata and Git-backed process template for the existing book-of-the-week workflow. The current workflow already exists in work-engine/scripts/seed-templates.ts and content/tasks/templates/book-of-the-week.md; this issue is about making it operator-ready, not inventing a new workflow type.

Primary files and source material:

• work-engine/scripts/seed-templates.ts
• content/tasks/templates/book-of-the-week.md
• work-engine/docs/templates.md
• work-engine/docs/specs.md
• docs/operations-manager-platform-jtbd.md
• content/overview/reference/events-slack-book-of-the-week.md
• content/community/book-of-the-week/sops/
• content/community/book-of-the-week/templates/
• content/social-media/reference/posts-book-of-the-week.md

The final workflow must preserve these operator semantics:

• Recurring operating cadence: Book of the Week is a weekly Monday-Friday community workflow, but bundle creation remains manual because it depends on an author/publisher agreeing and a date being confirmed. The anchor date is Monday of event week. Operators should instantiate the workflow about 21 days before that Monday once a candidate book/date exists.
• Task due dates: task dates are derived from the Monday anchor date using offsets, including outreach at -21, date confirmation at -20, schedule confirmation at -19, setup through -16, newsletter/social prep at -8 to -6, event-week announcements at 0, author Q&A at +1, winner selection at +4, winner email collection at +5, Slack winner announcement at +6, and publisher/author handoff at +7.
• Book/sponsor/website/social proof: the workflow must capture book title/author context, publisher or sponsor fulfillment contact, book/publisher source link, public website page link, LinkedIn/X/Slack announcement proof links, author-share proof where available, and winner handoff proof.
• Follow-ups: author outreach, date confirmation, author Slack invite, author share request, missing winner emails, and publisher/author handoff must tell the operator when to mark a task waiting, whom they are waiting for, and what followUpAt date to set.
• SOPs in context: tasks should carry instructionDocId, instructionStepId where useful, systems, phase, and validation/proof metadata so the operator opens the relevant SOP or template from the task instead of browsing the docs tree.
• Completion criteria and reminders: due/overdue reminders should come from task dates; missing-evidence reminders should come from required links/proof requirements; follow-up reminders should come from waitingFor + followUpAt when a reply or asset is pending.

Implementation Requirements

Update the Book of the Week seed/template mapping so it is comparable in richness to the podcast metadata already present in work-engine/scripts/seed-templates.ts:

• Add Book of the Week phases such as author-outreach, book-and-page-setup, pre-event-promotion, event-week, and giveaway-closeout, mapped to workflow stages preparation, announced, after-event, and done.
• Add a sourceDocIds list for the task template, main reference, relevant SOPs, and reusable templates.
• Add or expand bundle link definitions for operator proof, at minimum:
  • Author email
  • Publisher or sponsor contact
  • Book or publisher source link
  • Website link
  • LinkedIn announcement
  • X announcement
  • Slack announcement
  • Author share proof
  • Winner announcement
  • Winner email handoff
• Add task-level instructionDocId, instructionStepId where a clear step exists, phase, systems, and validation for each Book of the Week task.
• Use requiredLinkName and/or proofRequirement for tasks that must not be completed without proof, including website page creation, social announcements, Slack announcements, winner announcement, and publisher/author handoff.
• Keep fill-newsletter-announcement assigned to Valeriia and the rest defaulted to Grace unless the source docs clearly justify another owner.
• Keep the workflow manual (triggerType: manual). Do not add automatic bundle generation unless a separate issue expands recurring config support for parameterized Book of the Week runs.
• Regenerate or manually align content/tasks/templates/book-of-the-week.md so the Git-backed template reflects the executable metadata.
• Update documentation in work-engine/docs/templates.md only as needed to keep the canonical reference aligned with the executable template.
• If SOP/template docs need minor metadata fixes to support contextual linking, keep changes scoped to Book of the Week docs and preserve the existing converted content.

Suggested task mapping details:

Ref ID	Offset	Phase	Completion proof / reminder behavior
reach-out-to-book-authors	-21	author-outreach	Record outreach channel/source. If no reply, mark waiting for author with follow-up in 3 business days.
agree-on-a-date	-20	author-outreach	Confirm Monday-Friday event week. If author has not confirmed, set waitingFor author and followUpAt.
change-status-confirmed	-19	author-outreach	Confirm schedule spreadsheet status is confirmed; external-status/comment proof is required.
fill-airtable-form-author	-18	book-and-page-setup	Author/person form submitted; capture author email.
fill-airtable-form-book	-17	book-and-page-setup	Book form submitted; capture book/publisher source and cover/description source.
create-web-page	-16	book-and-page-setup	Required Website link; completion blocked until public page URL exists.
fill-newsletter-announcement	-8	pre-event-promotion	Newsletter Book of the Week block prepared, assigned to Valeriia.
announce-event-linkedin	-7	pre-event-promotion	Required LinkedIn announcement link or scheduled-post proof.
remind-author-about-event	-7	pre-event-promotion	Reminder sent with website link; if author has not accepted Slack invite, set follow-up.
ask-authors-share-event	-6	pre-event-promotion	Capture author-share proof if available; otherwise record waiting/follow-up.
announce-book-event-linkedin	0	event-week	Required LinkedIn proof; completion advances stage to announced if not already announced.
comment-from-alexey-linkedin	0	event-week	Comment proof or [HUMAN] note if Alexey must perform it directly.
announce-book-event-twitter	0	event-week	Required X announcement proof link.
invite-author-to-slack	0	event-week	Confirm invite sent/accepted; waiting state if author has not joined.
schedule-announcement-slack	0	event-week	Slack announcement scheduled with cover and copied template.
announce-book-slack-channels	0	event-week	Required Slack announcement proof link in #book-of-the-week and/or #announcements.
authors-answer-questions	+1	event-week	Monitor that author is answering questions; if inactive, follow up with author.
select-winners	+4	giveaway-closeout	Winners selected by author or randomizer; stage advances to after-event.
collect-emails-from-winners	+5	giveaway-closeout	Winner emails collected. Missing emails require waiting/follow-up for winners by Tuesday/Wednesday.
announce-winners-slack	+6	giveaway-closeout	Required Winner announcement Slack proof link.
contact-publisher-give-emails	+7	giveaway-closeout	Required Winner email handoff proof to publisher/author; stage advances to done.

Acceptance Criteria

• The seeded book-of-the-week template has phases, sourceDocIds, enriched bundle link definitions, and task-level doc context (instructionDocId, useful instructionStepId, phase, systems, and validation/proof metadata).
• The seeded workflow still has exactly 21 Book of the Week tasks unless the implementer documents a source-backed reason for changing the count.
• The template remains manually triggered and clearly documents the weekly Monday-Friday cadence and Monday anchor date.
• Instantiating the template for a Monday anchor date produces the expected due dates from anchorDate - 21 through anchorDate + 7, including the Valeriia newsletter task at anchorDate - 8.
• Required proof is enforced through existing metadata for website, LinkedIn, X, Slack announcement, winner announcement, and winner email handoff tasks.
• Operator guidance for waiting/follow-up states is present for author outreach, date confirmation, author invite/share, author Q&A inactivity, missing winner emails, and publisher/author handoff.
• content/tasks/templates/book-of-the-week.md matches the executable seed template after export or manual alignment.
• work-engine/docs/templates.md remains consistent with the enriched Book of the Week workflow.
• Tests cover the enriched Book of the Week seed metadata, due-date offsets, required proof fields, phase/stage transitions, and assignee override for the newsletter task.
• Existing newsletter, podcast, webinar, workshop, recurring, and task completion behavior does not regress.
• [HUMAN] is used in acceptance notes or validation text for actions requiring external accounts or real production writes, such as posting from Alexey's LinkedIn account, Slack posting, Airtable submission, website publication, and emailing publishers.

Test Scenarios

Scenario: Seeded template exposes operator-ready metadata

Given: the local work-engine database is empty or reseeded
When: the seed templates script runs and /api/templates is queried
Then: the Book of the Week template includes the enriched phases, source doc IDs, expanded bundle links, task doc context, systems, validation, and required proof metadata.

Scenario: Anchor-date offsets produce the weekly operating schedule

Given: a Book of the Week bundle is instantiated with anchor date 2026-07-06 (Monday)
When: tasks are created from the template
Then: outreach is due 2026-06-15, date agreement is due 2026-06-16, website creation is due 2026-06-20, newsletter announcement is due 2026-06-28, event-week announcements are due 2026-07-06, winner selection is due 2026-07-10, and publisher/author handoff is due 2026-07-13.

Scenario: Required public proof blocks completion

Given: a Book of the Week task that produces a public link, such as website creation or Slack winner announcement
When: the operator tries to mark it done without the required URL/proof
Then: existing completion validation blocks the task and explains which proof is missing.

Scenario: Waiting follow-ups keep author and winner handoffs visible

Given: the author has not replied, has not joined Slack, or winners have not sent emails
When: the operator marks the relevant task as waiting
Then: the task records waitingFor, followUpAt, and a note, and it can surface as a follow-up due reminder without being marked done.

Scenario: SOPs and templates open from task context

Given: the operator opens a Book of the Week task in the workflow
When: they need instructions or message copy
Then: the task points to the relevant Book of the Week SOP/template context instead of requiring the operator to browse the docs tree.

Out of Scope

• Building new reminder UI, notification types, dashboards, or completion-blocking mechanics beyond using existing metadata fields.
• Creating an automatic recurring Book of the Week generator; this workflow remains manual because each run requires a confirmed author/book/date.
• Editing source repos outside dataops, including ../dtc-operations, ../datatasks, or ../podcast-assistant.
• Performing real Slack, LinkedIn, X, Airtable, Google Sheets, website, or publisher email actions.
• Rewriting all Book of the Week SOP prose or screenshots beyond small metadata/context fixes needed for this mapping.
• Changing unrelated workflow templates.

Dependencies

• Existing V1 task/template fields in work-engine/src/types.ts: phases, source doc IDs, instruction doc IDs, systems, validation, proof requirements, required link names, stages, waiting/follow-up fields, and bundle links.
• Existing Book of the Week converted SOPs/templates under content/community/book-of-the-week/.
• Existing seed/export scripts for runtime templates and Git-backed content templates.
• External-account verification is human-only and must be represented as [HUMAN] checks, not executed by agents.

Labels

Apply these issue labels after grooming:

• P1
• process-docs
• work-engine
• docs

Remove needs grooming once this body is saved.

Verification Commands

Run from the repo root unless noted:

cd work-engine && npm test
cd work-engine && npm run typecheck
cd work-engine && npm run build
cd work-engine && npm run export:templates
cd work-engine && npx playwright test e2e/seed-templates.spec.js
python -m pytest tests/docs_app/test_infra_template.py

Also inspect the diff before handoff:

git diff -- work-engine/scripts/seed-templates.ts content/tasks/templates/book-of-the-week.md work-engine/docs/templates.md content/community/book-of-the-week

[alexeygrigorev]

PM grooming complete. I rewrote the issue into an agent-ready spec for enriching the existing Book of the Week workflow with operator due dates, phases, contextual SOP/template metadata, required proof links, waiting/follow-up guidance, reminders, acceptance criteria, test scenarios, out-of-scope boundaries, dependencies, labels, and verification commands. I removed needs grooming and added docs; no repo files were edited.