From 63c17bcd340cda677087686e8f8b6d63c2607366 Mon Sep 17 00:00:00 2001 From: Parsa Khazaeepoul Date: Fri, 10 Jul 2026 22:12:10 -0700 Subject: [PATCH] Block publish on missing Notion instead of silently degrading An epic publish (bloomapi/bloom-mono#338) ran with no Notion connection and a stale local copy of these files: the Notion page was never created, the GitHub issue was a ~10-line summary that referenced a 'linked work item' that didn't exist, and the refs/ artifacts (data pulls, code research) existed only on one machine. The degraded path executed silently when the right move was to stop and connect. - notion skill setup: with no Notion tools/CLI, interactive sessions now block with the connection path and retry after connecting; only an explicit user skip returns NOTION SKIPPED BY USER. Headless runs keep the non-blocking NOTION UNAVAILABLE so cron/cloud never hangs on a prompt. - publish procedure: degraded mode is gated on those two explicit signals, sets the issue body to the full item.md (not the summary), records the skip in frontmatter, and the done-when now names the failure this PR is preventing. Co-Authored-By: Claude Fable 5 --- tyler/.claude/skills/notion/SKILL.md | 22 +++++++++++++++++----- tyler/references/publish-work-item.md | 15 ++++++++++++--- 2 files changed, 29 insertions(+), 8 deletions(-) diff --git a/tyler/.claude/skills/notion/SKILL.md b/tyler/.claude/skills/notion/SKILL.md index 70ff512..8b412fb 100644 --- a/tyler/.claude/skills/notion/SKILL.md +++ b/tyler/.claude/skills/notion/SKILL.md @@ -19,9 +19,20 @@ operation: `publish`, `upload`, or `pull`. `+notion search create fetch update attachment` and load what the operation needs (search, fetch, create-pages, update-page, create-attachment). Tool names vary by connector — match on the `notion` - prefix. If no Notion tools resolve and no `notion` CLI is on PATH, return - `NOTION UNAVAILABLE: ` — the caller proceeds - GitHub + local only and says so. + prefix. If no Notion tools resolve and no `notion` CLI is on PATH, do + **not** silently degrade — how to proceed depends on whether a user is + present: + - **Interactive session** (a human invoked the calling skill): stop and + tell the user Notion isn't connected, give the connection path + (`claude mcp add --transport http notion https://mcp.notion.com/mcp`, + then `/mcp` to authenticate), and wait. Retry after they connect. Only + if they explicitly choose to skip, return `NOTION SKIPPED BY USER` — + the caller then runs its degraded mode so every artifact still ends up + reachable from the GitHub issue. + - **Headless run** (cron, cloud, no user to ask): return + `NOTION UNAVAILABLE: ` and let the caller's degraded + mode carry the artifacts. Never block a headless run on a connection + prompt nobody can answer. 2. **Find the target database** — resolution order, most specific wins: 1. The project `CLAUDE.md`'s `Work-item tracking` section (`notion_data_source`) — per-repo override only. @@ -31,8 +42,9 @@ operation: `publish`, `upload`, or `pull`. the match with the user, and offer to save it into this skill's `config.yaml` so the search never repeats. -**Success criteria**: tools loaded and a data source resolved (or an explicit -`NOTION UNAVAILABLE`). +**Success criteria**: tools loaded and a data source resolved — or an explicit +`NOTION SKIPPED BY USER` (interactive) / `NOTION UNAVAILABLE` (headless); +never a silent fallback in an interactive session. ## Operation: publish (called by /create-feature, /create-epic, /create-issue) diff --git a/tyler/references/publish-work-item.md b/tyler/references/publish-work-item.md index 0e14ca9..5f64253 100644 --- a/tyler/references/publish-work-item.md +++ b/tyler/references/publish-work-item.md @@ -14,8 +14,15 @@ Used by `/create-feature`, `/create-epic`, and `/create-issue` after 4. Cross-link: add the Notion page URL to the GitHub issue body (`gh issue edit`), and record both in `item.md` frontmatter as `github:` and `notion:`. -5. On `NOTION UNAVAILABLE`, the issue must still carry everything a remote - `/do` needs — post each artifact as its own issue comment, wrapped in +5. Notion is not optional in an interactive session. If the notion skill + reports no connection, it blocks and helps the user connect (see its + setup step); the publish resumes at step 3 once connected. Degraded mode + below runs only on an explicit `NOTION SKIPPED BY USER`, or on + `NOTION UNAVAILABLE` from a headless run. +6. Degraded mode: the issue must carry everything a remote `/do` needs — + set the issue body to the **full `item.md` content** (not the summary), + record `notion: SKIPPED — re-run notion publish when connected` in the + frontmatter, and post each artifact as its own issue comment, wrapped in markers so Step 0 can harvest them back: ``` @@ -31,4 +38,6 @@ Used by `/create-feature`, `/create-epic`, and `/create-issue` after Done when: the issue exists, every artifact is reachable from it (Notion work item, or marker-delimited comments in degraded mode), and each of -issue / Notion page / item.md links to the others. +issue / Notion page / item.md links to the others. A publish that leaves +artifacts only on the local machine, or an issue that references a Notion +page that doesn't exist, is a failed publish — never that.