feat(kora): KR-FEAT-SLACK-DM ST3 — Slack app runbook

[rafe-walker]

Summary

Final ST of Feature 5. Pure docs; closes the KR-FEAT-SLACK-DM arc. Operator-facing checklist from "no Slack app" to "Joshua DMs Kora's bot and gets an echo reply."

Bucket spec: `kora_docs/17_cc_bucket_prompts/KR-FEAT-SLACK-DM_kora_joshua_dm.md`.

Base: `feature/phase2-upgrades` — NOT main.

Single deliverable

`kora_docs/15_status_and_roadmap/slack_app_setup_runbook.md` (405 lines)

Sections

1. Slack app creation — two paths:
   • Path A: Manual UI walkthrough
   • Path B: Paste-ready app manifest YAML (recommended) with all OAuth scopes (`chat:write` / `im:history` / `im:read` / `im:write`) + bot_events (`message.im`) + event_subscriptions request_url placeholder
2. Install to workspace — OAuth consent + xoxb-... token grab
3. Signing secret grab — Basic Information path + security framing
4. Doppler secrets — three envs into `kora-runtime-gateways`; `flyctl secrets import` + `shred` pattern; calls out the `KORA_SLACK_JOSHUA_USER_ID` fail-CLOSED behavior
5. Smoke test — DM → echo within 5s; operator-side log lines + JSONL round-trip schema (received + ok pair)
6. Troubleshooting matrix — diagnoses + fixes for:
   • URL-verification "Failed" (4 modes: signing-secret mismatch / daemon down / TLS cert / timestamp skew)
   • No reply received (7 modes, each tied to a specific `[kora.slack_dm.*]` log line for self-diagnosis)
   • Reply content wrong/truncated (echo-format-locked framing)
   • Reply in wrong thread (thread_ts fallback explained)
7. §4 Q4 — Dual signing-secret env transition note: legacy `gateway/platforms/slack.py` (`SLACK_SIGNING_SECRET`) vs new daemon listener (`KORA_SLACK_SIGNING_SECRET`); operator sets BOTH to same value during transition; rotates BOTH together; post-KR-2 cleanup path documented
8. Promotion to production — same sequence with `-c prd`; Joshua-decides-when gate
9. Operator obligations — monitor reply_failed rate, PAUSED-state communication, rotation cadence, JSONL rotation (operator-managed via logrotate / Fly log-tailing)
10. What's NOT in this feature — deferred to KR-FEAT-AI-RESPONSE-LOOP / KR-MCP-SEND-TOOLS / etc.
11. Cross-references — wires the runbook to all 4 prior PRs' code paths + the two existing roadmap docs + the R2 amendment

§5 ship checklist

• Base `feature/phase2-upgrades`
• Title format `feat(kora): KR-FEAT-SLACK-DM STn — `
• No code changes (pure docs)
• App manifest YAML paste-ready into Slack's import flow
• §4 Q4 dual signing-secret note covered
• Cross-references woven so operator can navigate without re-grepping

Test plan

• Joshua reads end-to-end before walking the actual Slack app setup
• Path B (manifest paste) verified: Slack accepts the YAML + shows Verified ✓ on Request URL
• Echo round-trip verified: DM "ping" → "Kora received: ping" within 5s
• At least one troubleshooting path validated by intentionally tripping it (e.g. unset `KORA_SLACK_JOSHUA_USER_ID` + verify the expected log line + fail-CLOSED drop)

Feature 5 closes

After this PR merges, the KR-FEAT-SLACK-DM 3-ST cascade is complete:

• ST1 (feat(kora): KR-FEAT-SLACK-DM ST1 — inbound handler + identity check + JSONL log #119) — inbound 5-filter handler + identity check + JSONL + state-gate
• ST2 (feat(kora): KR-FEAT-SLACK-DM ST2 — outbound chat.postMessage + echo reply #122) — outbound `chat.postMessage` + echo reply + retry policy + dead-letter
• ST3 (this PR) — operator runbook

Joshua can DM Kora and get echo replies once the operator walks the runbook through staging + prod. The AI-driven response generation that replaces the echo is the deferred `KR-FEAT-AI-RESPONSE-LOOP` follow-on; the Slack-DM scaffold is the stable interface that follow-on consumes.

Next bucket candidates (PM's call)

• KR-FEAT-AI-RESPONSE-LOOP — replace ST2's echo with LLM-driven response generation
• KR-MCP-SEND-TOOLS — expose `kora__send_slack_dm` + `kora__send_email` via `/mcp` for agent-driven sends

🤖 Generated with Claude Code