Workflows first run: hand missing signups and emails to an agent

Map: Map: build the Workflows first run, from template gallery to first send
Spec: Spec: Workflows first run

Cast: Opus 5.5 (UI)

Question

When the project lacks signups or emails, can a user hand the fix to an agent without editing code?

Delivers end to end. Spec section "Missing data handed to an agent", with the workflows first run agent help shown and workflows first run agent prompt copied events. Builds on the tailored template gallery.

Above the gallery, at most one banner:
- no seen signup event (the welcome template's starts_on.events): info, the user can test an email now, and real signups need the app to tell PostHog when someone signs up;
- else no email person property definition: warning, people have no email yet, so they would miss the emails.
Each banner has "Copy prompt for your coding agent" through AgentPromptButton, with a ready prompt for its case, and "Let the Wizard do it", which reveals the command from useWizardCommand in WizardCommandBlock. The Wizard part hides when isCloudOrDev is false.
The email check reads property definitions, never a person scan.
Copy through /writing-user-facing-copy, including its Wizard naming rule. The prompts are written fresh for this ticket.

Test seams. A kea logic test with event and property definitions mocked at the HTTP layer: which banner shows for no signup event, for no email property, and for neither. Stories of both banners at full width and 520px.

Write scope. The first-run folder under products/workflows/frontend/, and tests and stories. Reuse AgentPromptButton, useWizardCommand and WizardCommandBlock as they are.

Acceptance criteria

A project without a signup event shows the signup banner; one with signups but no email property shows the email banner; one with both shows none.
The copy button puts the case's prompt on the clipboard; the Wizard button shows the setup agent command.
Screenshots on this ticket.

How to build (map #253)

/implement + /tdd red-green-refactor, outside-in, at the seams named above. The frontend mocks the API at the HTTP layer. Mock only what is external: the LLM and the PostHog analytics client.
Repo skills apply where the diff touches their area: /writing-tests, /improving-drf-endpoints, /writing-ui-components, /writing-kea-logics, /adopting-generated-api-types, /placing-product-frontend-code, /writing-user-facing-copy, /writing-code-comments.
Branch from upstream/master, push to the fork, open a draft PR on PostHog/posthog against master. A stacked PR carries its parent's commits and a "Stacked on" note.
Then /qa-swarm. Shipped means a draft PR it handed off. Never mark ready, enqueue or merge.
Public repo: state sender rules as product rules. Fixture addresses use example.com. The prototype is throwaway: read it for behavior, never copy or cherry-pick it.

Runtime: Claude Code background agent (conductor thread on devbox-michaelr-3)
Worker: impl-265, Claude Opus 5.5 (routine UI)
Worktree: /home/coder/.t3/worktrees/posthog/fr-265, branch feat/workflows-first-run-agent-help, stacked on PostHog#111816
Cap: 4 hours from 12:27 UTC
CodeRabbit slot: 1 of 3

Claimed by conductor worker impl-265 (Claude Code background agent, Opus 5.5).

Worker transcript: /tmp/claude-1001/-home-coder--t3-worktrees-posthog-t3code-1d6de0ea/6f4018e1-a32c-4b89-bae8-f0ca1d7056a8/tasks/a6f2c8e47ec5846f3.output. Deadline wake set for 16:31 UTC.

Red. Commit 78d0653 adds firstRunAgentHelpLogic.test.ts against a stub logic that answers no missing data and captures nothing.

pnpm --filter=@posthog/frontend exec jest products/workflows/frontend/firstRun/firstRunAgentHelpLogic.test.ts

    ✕ asks a project without a signup event for help with signup_event (82 ms)
    ✕ asks a project with signups but no email property for help with email (32 ms)
    ✕ asks a project without a signup event or an email property for help with signup_event (24 ms)
    ✓ asks a project with signups and an email property for help with null (28 ms)
    ✕ reports a copied prompt with the data it fixes (25 ms)
  ● firstRunAgentHelpLogic › asks a project without a signup event for help with signup_event
    Expected: "signup_event"
    Received: null
  ● firstRunAgentHelpLogic › asks a project with signups but no email property for help with email
    Expected: "email"
    Received: null
  ● firstRunAgentHelpLogic › asks a project without a signup event or an email property for help with signup_event
    Expected: "signup_event"
    Received: null
  ● firstRunAgentHelpLogic › reports a copied prompt with the data it fixes
    Expected: "workflows first run agent prompt copied", {"missing": "email"}
Tests:       4 failed, 1 passed, 5 total

The fourth case passes on the stub by design: a project with signups and an email property gets no banner.

Green. Commit ed581e7 implements the logic and the banner. Every assertion of the red test is unchanged; only the parameterized test name now reads "missing data: …".

pnpm --filter=@posthog/frontend exec jest products/workflows/frontend/firstRun --verbose

    ✓ copies the prompt for a project without a signup event (239 ms)
    ✓ copies the prompt for a project without an email property (130 ms)
    ✓ shows the setup agent command when asked to let the Wizard do it (124 ms)
    ✓ asks a project without a signup event for help with missing data: signup_event (198 ms)
    ✓ asks a project with signups but no email property for help with missing data: email (109 ms)
    ✓ asks a project without a signup event or an email property for help with missing data: signup_event (95 ms)
    ✓ asks a project with signups and an email property for help with missing data: null (94 ms)
    ✓ reports a copied prompt with the data it fixes (95 ms)
    ✓ shows a project without workflows the workflows-first-run-gallery (300 ms)
    ✓ shows a project with a workflow the workflows-table (72 ms)
    ✓ tailors the gallery to a project that sends signups and pageviews (189 ms)
    ✓ tailors the gallery to a project that sends only pageviews (105 ms)
    ✓ tailors the gallery to a project that sends several signup events (90 ms)
    ✓ tailors the gallery to a project that only planned a signup event and sends pageviews (87 ms)
    ✓ tailors the gallery to a project that sends only events no template starts on (91 ms)
    ✓ tailors the gallery to a project that sends no events (89 ms)
    ✓ asks for every event the email templates can start on in one request (88 ms)
    ✓ reports the gallery once its fit is known (87 ms)
    ✓ reports picking the recommended starter and opens it (92 ms)
    ✓ reports picking another ready template and opens it (93 ms)
    ✓ reports picking a template that is not ready and opens it (87 ms)
    ✓ offers a retry when the templates request fails, and recovers on it (93 ms)
    ✓ offers a retry when the event definitions request fails, and recovers on it (95 ms)
Tests:       23 passed, 23 total

The component test FirstRunAgentHelp.test.tsx was written after the banner existed, so here is its red by mutation on the final tree: swap the signup prompt for the email prompt and drop the onRun report.

    ✕ copies the prompt for a project without a signup event (1245 ms)
    ✕ copies the prompt for a project without an email property (127 ms)
    ✓ shows the setup agent command when asked to let the Wizard do it (116 ms)
  ● FirstRunAgentHelp › copies the prompt for a project without a signup event
    Expected: StringContaining "Capture an event named exactly \"user signed up\""
  ● FirstRunAgentHelp › copies the prompt for a project without an email property
    Expected: "workflows first run agent prompt copied", {"missing": "email"}
Tests:       2 failed, 1 passed, 3 total

Screenshots for #265, rendered from WorkflowsFirstRun.stories.tsx in headless Chromium against the whole app at /workflows with the flag on. Storybook mock data only. The narrow column uses a 552px viewport, which gives the scene 520px.

Project	Full width	520px scene
No signup event: info banner
No signup event, Wizard shown
Signups but no `email` property: warning banner
Signups and `email`: no banner

Files live on the fork branch assets/workflows-first-run-agent-help at 2b264d9d080, because hogli pr:upload-image lacked permission on PostHog/pr-assets for this account.

Decisions where the ticket left room (best guess, recorded per the map's autonomy rule):

Signup check reuses the gallery. firstRunAgentHelpLogic connects to firstRunGalleryLogic.galleryTemplates and reads the welcome template's matchedEvent, which already applies the last_seen_at rule from Workflows first run: tailored template gallery on the empty Workflows tab #258. No second event-definitions request.
Email check is one property-definitions request (type=person, properties=email, limit=1), sent on mount. Sending it even when the signup banner wins keeps the logic free of ordering between the two loads; the request is a single indexed lookup.
No banner while unsure. If the welcome template is missing from the gallery, or a request fails, no banner shows. The banner is a hint, so a failed lookup does not get its own error state; the gallery keeps its own retry.
AgentPromptButton keeps coding-agent destinations. Default is the clipboard, so the button reads "Copy prompt for your coding agent". The dropdown also offers Claude Code, Cursor, Codex and PostHog Desktop; PostHog AI is left out because it cannot edit app code. workflows first run agent prompt copied fires on any run with missing, as the spec defines.
"Agent help shown" fires once per mount, when the missing data resolves.
Signup prompt names user signed up, the welcome template's own trigger event and the first event in its starts_on.
Wizard description is the default one from WizardCommandBlock ("Auto-detects your framework, installs the SDK, and sets up event capture."), so no claim is made that the setup agent adds a specific event.
Extra seam: a component test (FirstRunAgentHelp.test.tsx) covers the two acceptance points the logic test cannot see: the copy button puts the case's prompt on the clipboard and reports the copy, and "Let the Wizard do it" shows the command.

Recast (Michael, 2026-10-05): the Opus 5.5 worker stopped on provider overload or rate limit. Continuing on GPT-6.1 Sol through a Claude Code codex:codex-rescue background agent, worker impl-265-gpt, in the same worktree /home/coder/.t3/worktrees/posthog/fr-265. Cap: 4 hours from 13:24 UTC. CodeRabbit slot: 1 of 3.

Worker transcript (codex-rescue bridge agent): /tmp/claude-1001/-home-coder--t3-worktrees-posthog-t3code-1d6de0ea/6f4018e1-a32c-4b89-bae8-f0ca1d7056a8/tasks/ac300eb05c3012df7.output. Deadline wake set for 17:29 UTC.

Lane orphaned: the codex:codex-rescue bridge runs Codex in a sandbox without network or the flox environment, so it could not reach GitHub, push, or run the gate. No changes were made; the worktree WIP is intact. Redispatching as a T3 delegated child on GPT-6.1 Sol with full access, the path that shipped #257. Worker impl-265-gpt-r2. Cap: 4 hours from 13:26 UTC.

Runtime: T3 delegated child
Task: node:delegated-task:command%3Amcp%3A76836cff-6bc5-4020-b351-b1d68e6aaa47%3Adelegate-task%3Afr-265-r2
Deadline wake: 17:29 UTC

Note

🤖 GPT-6.1 Sol responding on behalf of Michael

Taking over as impl-265-gpt-r2. I will inspect the remaining edit, rerun the local gate on the final head, and finish qa-swarm on draft PostHog#111902. The result and proof will land here; the PR stays draft.

Note

🤖 GPT-6.1 Sol responding on behalf of Michael

Final local proof for c8e2ef102952c63a18c26d8716118685e08e3422, draft PostHog/posthog#111902.

The inherited edit is kept in ada8b792f2ce2. It makes the action clipboard-only, explains browser/server person-property capture, adds setup-agent checks, and exposes Wizard expansion to assistive technology. CodeRabbit's local-state finding is fixed in c8e2ef102952c by keeping Wizard visibility in Kea.

Commands and observed results

All environment-dependent commands ran from this worktree's root through .codex/with-flox.

pnpm --filter=@posthog/frontend fix
Found 3735 warnings and 0 errors.
Oxfmt completed successfully.
Exit 0.

pnpm --filter=@posthog/frontend typescript:check
No errors reported by tsgo.
Exit 0.

pnpm --filter=@posthog/frontend typegen:file products/workflows/frontend/firstRun/firstRunAgentHelpLogic.ts
1 logic type up to date!
Exit 0.

pnpm --filter=@posthog/frontend exec jest products/workflows/frontend/firstRun --runInBand --verbose
Test Suites: 4 passed, 4 total
Tests:       23 passed, 23 total
Snapshots:   0 total
Exit 0.

The Jest suite exercises missing-signup priority, alternative seen signup events, email property definitions, analytics, both clipboard prompts, Wizard reveal, and the parent gallery behavior. The original red/green proof remains valid.

The actual pre-push hook ran hogli ci:preflight --strict with zero failures, and the push succeeded. A separate scoped run, hogli ci:preflight --strict --against origin/feat/workflows-first-run-gallery, checked the six files in this layer with zero failures.

The hook's freshness advisory refers to the fork's older origin/master. The branch shares today's upstream base, and git merge-tree --write-tree HEAD upstream/master completed without conflicts. The hook's lockfile check reordered existing dependencies; that incidental uncommitted ordering change was restored.

Visual proof from the build covers both banners, the expanded Wizard, and no banner at full width and 520px. Final-head Storybook serves successfully, but T3 collaborative-browser navigation times out, so the final copy/style changes lack a fresh screenshot. No real coding-agent paste or backend round trip was checked.

Note

🤖 GPT-6.1 Sol responding on behalf of Michael

Resolved with draft PostHog/posthog#111902, stacked on PostHog#111816. Clean head: c8e2ef102952c63a18c26d8716118685e08e3422. The working tree is clean, the fork branch and PR match that head, and the PR remains draft.

Proof: final local gate, red, green and component mutation red, build screenshots. Typecheck, frontend fix, affected Jest tests, scoped typegen and the actual pre-push hook passed on the final code. The pre-push hook reported zero failures and both finishing commits are pushed.

qa-swarm handoff: two rounds, the second clean after triage on the final head. Each round used fresh GPT-6.1 Sol reviewers for six lenses and a whole-change review, plus Claude Opus 5.5 for UI. Every reviewer covered all six changed files. No open decision, in-scope fix, or call remains.

CodeRabbit: one local-state finding fixed in c8e2ef102952c; one signup-alias finding withdrawn; two inherited template concerns retained as rollout follow-ups. The bot verified the fix and accepted the scope replies. CLI skipped because it is signed out.
GPT panel: no fixes or rejects; two reports identified the same shared clipboard analytics limitation, recorded as one follow-up.
Claude UI: no fixes; two presentation hypotheses rejected across the rounds; two shared-control follow-ups recorded.
Merge risk: low. A wrong definition check can show misleading guidance; the default-off flag and focused tests limit it. This layer has 248 production additions and 255 test/story additions, with 6 test/story deletions.

Calls made: kept the inherited finishing edit. Clipboard-only matches the literal copy action instead of offering other agent destinations; prompts cover browser and server SDKs; Wizard guidance asks users to verify the specific missing instrumentation. The signup check reuses the gallery's welcome match, the email check reads definitions, and unknown/failed hint lookups do not block the gallery. A late optional hint may move the grid; delaying the whole gallery for that request was rejected.

Follow-ups: AgentPromptButton.onRun records copy attempts before success and retains a redundant single-destination menu. The ticket explicitly says to reuse that shared control unchanged. Parent onboarding-route alignment is already named on the map; matched-event and empty-trigger binding belong to the existing creation slice #260. No other work was dispatched or ticket edited.

Gaps: upstream workflows wait for fork approval, as the map permits. Hosted CodeRabbit verified the final-head fix and scope replies, but no full incremental review arrived. All existing findings are triaged. Build screenshots cover the required states and widths, but T3 browser navigation prevented fresh screenshots after the final copy/style change. No real backend round trip or coding-agent paste was checked. GitHub rejected assigning the PR author with ReplaceActorsForAssignable; the PR description names its human-driven ownership.

Read first: firstRunAgentHelpLogic's definition lookup and priority selector, then the prompt and Wizard wiring in FirstRunAgentHelp. No human reply drafts or pending questions remain. Michael reviews and marks the PR ready himself.

Navigation Menu

Repository navigation

Workflows first run: hand missing signups and emails to an agent #265

Question

Acceptance criteria

How to build (map #253)

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Workflows first run: hand missing signups and emails to an agent #265

Description

Question

Acceptance criteria

How to build (map #253)

Activity

Silthus commented on Oct 5, 2026

Silthus commented on Oct 5, 2026

Silthus commented on Oct 5, 2026

Silthus commented on Oct 5, 2026

Silthus commented on Oct 5, 2026

Silthus commented on Oct 5, 2026

Silthus commented on Oct 5, 2026

Silthus commented on Oct 5, 2026

Silthus commented on Oct 5, 2026

Silthus commented on Oct 5, 2026

Silthus commented on Oct 5, 2026

Silthus commented on Oct 5, 2026

Silthus commented on Oct 5, 2026

Silthus commented on Oct 5, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions