From 522a1fab9981cce420b9a34628ed77dc153a1d9f Mon Sep 17 00:00:00 2001 From: "Vincent (Wen Yu) Ge" Date: Wed, 15 Jul 2026 18:42:08 -0400 Subject: [PATCH] fix(skills): unblock the two report-step failure loops seen in terra telemetry MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Wizard remark telemetry from the gpt-5.6-terra rollout (2026-07-15) shows two recurring frictions in the report/notebook step, ~10 mentions in the first hour, all recovered but each burning retries: - notebooks-create payloads failing to parse because the report markdown was pasted into the JSON literal unescaped. The notebook skill now spells out the escaping contract (newlines, quotes, backslashes → one single-line string), says to Read the finished report first, names the exact tool so no tool search is needed, and forbids trimming the report to dodge a parse failure. - the report task erroring on re-runs because harnesses refuse to overwrite a file that wasn't read. The report skill now distinguishes the fresh-write case from the replace-a-leftover case. Generated-By: PostHog Code Task-Id: 843d9848-d7ad-4bab-96d2-a78e0411251f --- .../integration-v2/notebook/description.md | 17 ++++++++++++++--- .../skills/integration-v2/report/description.md | 5 ++++- 2 files changed, 18 insertions(+), 4 deletions(-) diff --git a/context/skills/integration-v2/notebook/description.md b/context/skills/integration-v2/notebook/description.md index d289b222..a2b0d244 100644 --- a/context/skills/integration-v2/notebook/description.md +++ b/context/skills/integration-v2/notebook/description.md @@ -4,9 +4,13 @@ Once `posthog-setup-report.md` exists, mirror it into a shareable PostHog notebo so the user has an in-app copy to link and comment on. The notebook is an extra copy, not a replacement — keep the local report file in place. -Call `notebooks-create` through `posthog_exec` with a `title` (e.g. -`PostHog setup (wizard) – `) and `content` set to a single markdown -node that wraps the report verbatim: +First `Read` the finished `posthog-setup-report.md` — don't reconstruct the +report from memory, and don't try to read it before the report step has written +it. + +Then call `notebooks-create` through `posthog_exec` — that exact tool name, no +tool search needed — with a `title` (e.g. `PostHog setup (wizard) – `) +and `content` set to a single markdown node that wraps the report verbatim: ```json { @@ -17,6 +21,13 @@ node that wraps the report verbatim: } ``` +The `markdown` value is a JSON string, so the report's raw contents cannot be +pasted in verbatim: escape every newline as `\n`, every double quote as `\"`, +and every backslash as `\\`, yielding one single-line string. Getting this wrong +is the most common failure in this step — the tool call fails to parse and you +burn attempts re-escaping. If the payload is rejected, fix the escaping; do not +trim or summarize the report to make it fit. + Take the `short_id` from the response, build the URL as `/project//notebooks/`, and emit it on its own line in your final message with this exact marker so the wizard surfaces it: diff --git a/context/skills/integration-v2/report/description.md b/context/skills/integration-v2/report/description.md index 197d9978..7ccb95f6 100644 --- a/context/skills/integration-v2/report/description.md +++ b/context/skills/integration-v2/report/description.md @@ -1,7 +1,10 @@ # Write the setup report Write `posthog-setup-report.md` at the project root summarizing the integration. -It is a new file you create — write it directly, do not read it first. +When the file doesn't exist, write it directly — don't attempt a read first. If +a previous run left one behind, `Read` it, then replace it wholesale (harnesses +refuse to overwrite a file that wasn't read; nothing in the old report is worth +merging). Draw on two sources only: - the run's queue log — `.posthog-wizard-cache/queue.json`, which holds each