Docs: change a code-managed template with an agent, PostHog Code or PostHog AI, and where source details come from #507

Activity

1. Silthus

   added

   wayfinder:implement

   on Oct 17, 2026
2. Silthus

   added a parent issue on Oct 17, 2026

   • Map: send code-managed email templates with one PostHog call #461
3. Silthus

   marked this as blocked on Oct 17, 2026

   • Open a PR: draft PR route for a code-managed template's file #505
4. Silthus

   changed the title [-]Docs: edit a code-managed template in PostHog, and the PR error codes[/-] [+]Docs: change a code-managed template with your agent, and where source details come from[/+] on Oct 17, 2026
5. Silthus

   unmarked this as blocked on Oct 17, 2026

   • Open a PR: draft PR route for a code-managed template's file #505
6. Silthus

   marked this as blocked by 2 issues on Oct 17, 2026

   • Edit with your agent: copy a prompt for a code-managed template's file #503
   • posthog-node: fill the template source repository, path and ref on upload #510
7. Silthus

   changed the title [-]Docs: change a code-managed template with your agent, and where source details come from[/-] [+]Docs: change a code-managed template with an agent, PostHog Code or PostHog AI, and where source details come from[/+] on Oct 17, 2026
8. Silthus

   marked this as blocked on Oct 17, 2026

   • Request a change: start a PostHog Code task that opens a PR for a code-managed template #513
9. Silthus

   self-assigned this

   on Oct 17, 2026
10. Silthus commented on Oct 17, 2026

    

    Silthus

    on Oct 17, 2026

    OwnerAuthor

    More actions

    Decision (Michael, 2026-10-17): keep the rule. request_change refuses calls from inside a PostHog Code sandbox. PostHog AI and Slack runs come from such a sandbox, so for a code-managed template they do not call it. Instead they hand the person the template link, where "Run with PostHog Code" opens the PR in one click. An agent that can reach the repository still edits the file itself.
11. Silthus commented on Oct 17, 2026

    

    Silthus

    on Oct 17, 2026

    OwnerAuthor

    More actions

    Runtime: T3 child task
    Task: node:delegated-task:command%3Amcp%3A1b2eaa74-4f92-44bb-9856-6c98e457cb24%3Adelegate-task%3Awf-email-impl-507-1
    Cast: Opus 5.5, high.
12. Silthus commented on Oct 17, 2026

    

    Silthus

    on Oct 17, 2026

    OwnerAuthor

    More actions

    Note

    🤖 Opus 5.5 responding on behalf of Michael

    Resolution

    Shipped: two commits on Silthus:docs/transactional-email-api, the branch of draft PostHog/posthog.com#21306. The PR description is updated. The PR stays a draft.

    • 6aa5dd523 docs(workflows): change a code-managed template, and where its source comes from
    • 3f9db72ad docs(workflows): fix review findings on changing a code-managed template

    fleet proof gate passes on 3f9db72ad: live-run evidence at HEAD, HEAD reviewed in final read 4.

    What shipped

    • Change a code-managed template:
      • Edit with your agent: complete the sentence, copy the prompt. The example prompt is the builder's output for an example.com-style repository. Agents get the same text in change_prompt_starter and change_prompt_context.
      • Run with PostHog Code: what the task does, the four disabled reasons, and errors in the popover. Also the route POST …/messaging_templates/:id/request_change/, its auth (task:write, editor access to Workflows, no project secret key), the 201 body, and the MCP tool.
      • Ask PostHog AI or the Slack bot: they run inside PostHog Code, so they can't open a pull request. They give you the template link, and Run with PostHog Code opens it. An agent with a checkout edits the file itself.
      • Copy the HTML file: for a template without a file. Name the file after the key. The text-part note.
      • When the change goes live: copying a prompt or a file, or starting a task, changes nothing in PostHog until the app sends or uploads the file.
    • Where the source details come from: the source option of uploadTemplate(), the GitHub Actions, GitLab CI, Vercel and Railway variables and their order, the full-hash rule for refs, the git checkout fallback, the path rules, and what happens when nothing is found (repository and ref left out, PostHog keeps the stored value).
    • Seven error anchors, each quoting the server's detail, why and fix verbatim: instruction_missing, template_not_managed_by_code, template_repository_missing, template_repository_unsupported, github_repository_not_connected, posthog_code_not_available (its four reasons as a table), posthog_code_run_failed.
    • Updated: the immutable fix to the server's new text, and the change request route in invalid_request, not_found, permission_denied, the beta note and "Before you start".

    Proof

    • Anchor check (the Docs: transactional email API page for code-managed templates, an anchor per error code #475 check, extended):
      • The strings for the change request codes come from the server code by a Python AST pass over template_change_requests.py, template_ownership.py and message_templates.py at 60fb98f06a5.
      • The 27 earlier codes keep Docs: transactional email API page for code-managed templates, an anchor per error code #475's strings, except the immutable fix, which the server replaced.
      • Red on c86c7a6a9: 25/34. The seven codes have no anchor, and immutable and invalid_request miss the new fix text.
      • Green on 3f9db72ad: 34/34.
      • Every docs_url the route emits (…/transactional-email-api#<code>) resolves. A plain navigation to #template_repository_missing lands on the section.
    • Links: all 59 in-page # links on the rendered page have a target.
    • Screenshots from the local dev server (GATSBY_MINIMAL=true pnpm start), both sections and an error anchor, light at 1440 px and dark at 820 px, are in the PR body.
    • Lint: the pre-commit hook (markdownlint, Prettier) passed on both commits. No em or en dashes.
    • Gaps:
      • Vale isn't installed on this box.
      • No production gatsby build, so no markdown twin was generated locally.
      • No separate mutation run: the dev server's develop process died on a second live reload. The red run already shows the check catching one changed sentence (the old immutable fix).

    Review

    Fresh Claude subagent, Opus 5.5, high effort, read-only. Recorded with fleet proof review-start and review-finish.

    • Round 2 on 6aa5dd523: 0 high, 1 medium, 13 low. All held and are fixed in 3f9db72ad.
      • Medium: an agent that gets the sandbox refusal wasn't told where the template link is. It is the last line of change_prompt_context.
      • Low: among others, the detection order didn't hold for path, the absolute-path fallback was missing, Copy HTML file has to be named after the key, the "Checking the GitHub connection" reason was missing, and an app that sends by key needs an upload after the merge.
    • Final read 4 on 3f9db72ad: all resolved, and the five new claims hold against the code. PASS.

    Calls made

    • 👤 What do PostHog AI and the Slack bot do for a code-managed template? They hand the person the template link, where Run with PostHog Code opens the pull request. The page never says they open a PR.
    • 🤖 How to quote the change request errors detail, why and fix as a list per code, and posthog_code_not_available's four reasons as a table.
    • 🤖 Where the anchor check gets its strings From the server code by AST, so a server text change fails the check.
    • 🤖 The UI copy source Stack A copy from spec/template-agent-edit at 0960e3de116 (feat(workflows): edit a code-managed email template with your agent PostHog/posthog#118980, newer than the copy merged into stack B), the button copy from spec/template-request-change at 60fb98f06a5.
    • 🤖 Link to PostHog Code docs None. posthog.com has no PostHog Code page, so the page names it without a link.

    Spec and code differences (the page follows the code):

    Topic	Spec #502	Code
    PostHog AI and Slack	Call request_change and share the task link	Refused from a sandbox with posthog_code_not_available. They hand over the template link (decision above)
    Explicit source	Wins on every automatic upload	Only uploadTemplate() takes it. The upload after a send uses detection only
    Path	Omitted when nothing is found	Always has a value. Absolute outside the working directory, and the prompt then finds the file by key
    Ref variables	Taken as set	Count only as a 40- or 64-character hex hash
    Change request errors	Seven codes	Also invalid_request past 2,000 characters. posthog_code_not_available is 403 with four why/fix pairs, the rest 400
    Access	task:write and read access to the template	task:write and editor access to Workflows
    Disabled reasons	Three	Also "Checking the GitHub connection". The repository reason comes before "Describe the change first"
    Ref in the prompt	Shortened to 7 characters	Only a commit hash is shortened. A branch name shows as stored

    Follow-ups

    • Agents edit a code-managed template's file when they can, and request a change through PostHog Code when they can't #515 (open, landing in parallel): the page documents the sandbox decision. Two things to align there:
      • The MCP tool description of workflows-request-email-template-change still calls it the path for "a chat client with no checkout". From PostHog AI and Slack it answers 403 posthog_code_not_available.
      • If Agents edit a code-managed template's file when they can, and request a change through PostHog Code when they can't #515 lands with different agent behavior, the "Ask PostHog AI or the Slack bot" section and the note under posthog_code_not_available need an update.
    • Ship stack B: request a change through PostHog Code #517 (stack B server text): the immutable fix says "The next send uploads it." That misses an app that sends by key, which needs an upload. The prompt builder already makes that split. The page quotes the server, so it changes when the server text changes.
    • Publish order: feat: new scene for new pipeline configuration creation PostHog/posthog#21306 merges only after feat(messaging): upload, send and lock code-managed email templates PostHog/posthog#118924, posthog-js#5312, stack A (feat(workflows): edit a code-managed email template with your agent PostHog/posthog#118980) and stack B (Ship stack B: request a change through PostHog Code #517) ship. The merge-risk note in the PR says so.
    • Local dev notes for later workers:
      • posthog.com's gatsby develop breaks with DEBUG=1 in the environment (webpack inlines process.env.DEBUG in the debug package). Unset it.
      • It also breaks with a global url.<ssh>.insteadOf https://github.com/ rewrite, because gatsby-source-git compares remote URLs. GIT_CONFIG_GLOBAL=/dev/null for the server process avoids it.
    • Gaps carried: Vale and a production gatsby build on the page.
13. Silthus

    closed this as completedon Oct 17, 2026
14. Silthus commented on Oct 17, 2026

    

    Silthus

    on Oct 17, 2026

    OwnerAuthor

    More actions

    Note

    🤖 Opus 5.5 responding on behalf of Michael

    Docs follow stack B's reviewed head 0c3c8b87b51 (PostHog/posthog#119032). Pushed to PostHog/posthog.com#21306, which is still a draft:

    • c1380a99d docs(workflows): match the change request texts and access of the server
    • b805f1be6 and 2b0a7a224: final-read fixes

    What changed on the page:

    • hog_flow:read next to task:write, plus editor access to Workflows.
    • The button's access and length reasons. A non-GitHub repository now fails on click.
    • The server's new refusal texts, including the sandbox fix's page steps and the new immutable fix.
    • change_prompt_variables.

    Proof:

    • Anchor check, with strings read from the server code at 0c3c8b87b51: red 30/34 on 3f9db72ad, green 34/34 on 2b0a7a224.
    • All 63 in-page links resolve. The screenshots are in the PR.

    Review: final reads 5 to 7, Opus 5.5 at high effort, recorded with fleet proof.

    • Read 5: 3 low findings, fixed.
    • Read 6: 2 low findings in the fix lines, fixed.
    • Read 7: PASS.

    fleet proof gate passes on 2b0a7a224.