chore(skills): add writing-kea-logics skill

[pauldambra]

after yet again telling the robot not to use a selector
i thought maybe even more markdown files will help...

Problem

New engineers picking up the frontend hit kea conventions piecemeal —
which builder belongs where, when a reducer vs selector vs cache is
the right container, why we prefer listeners over kea-subscriptions,
when a logic should be keyed, and so on. Two narrow skills already
exist (using-kea-disposables, making-scenes-tab-aware) but neither
covers the foundational shape of a *Logic.ts file.

This adds writing-kea-logics as the foundational kea skill, with
companion-skill cross-references so the three together form a coherent
set without duplication.

Changes

New skill under .agents/skills/writing-kea-logics/:

• SKILL.md — slim entry point with core principles, a quick anatomy
  example, and a JTBD pattern index linking to references.
• Eleven JTBD-focused reference files: state-decision, loading-data,
  polling, forms, routing, persisting-state, reacting-to-changes,
  keyed-logics, connecting-logics, testing, anti-patterns. Each
  leads with the pattern, then why it's the right shape, then code,
  then anti-patterns.

Design choices worth flagging for reviewers:

• Cross-references rather than duplication. using-kea-disposables
  and making-scenes-tab-aware are linked from the relevant sections,
  not re-explained.
• Pattern teaching over file:line citations. Example file paths age
  faster than the patterns themselves, so references describe the shape
  with inline code and only point at canonical files at the level of
  "for a real form, search forms(...) in the repo".
• Small ## History sections at the bottom of
  reacting-to-changes.md and anti-patterns.md link to merged PRs
  (feat: kea disposables #38754, feat: kea disposables auto-tracks browser visibility and stops/starts disposables #40284, fix(data-warehouse): use disposables for polling in dataModelingLogic #48039–fix(managed-migrations): use disposables for polling in managedMigrationLogic #48042, fix(frontend): pause disposables added while page is hidden #58691) and commits where each
  anti-pattern or convention has a documented origin — readers wanting
  the why-it-changed context can follow back to the original change.

How did you test this code?

I'm an agent (PostHog Code). The only automated check I ran is
hogli lint:skills, which passes (39 skills lint-clean).

I did not exercise the skill through an end-to-end agent session.
Manual review by a human kea-fluent engineer is the right next step
to confirm the patterns and "why" framings match team intent.

Publish to changelog?

no

🤖 Agent context

Authored end-to-end by PostHog Code (Claude Opus 4.7) in a single
working session.

• Research: spawned an Explore subagent to survey the kea setup
  (frontend/src/initKea.ts), plugin usage, conventional block
  ordering, test patterns, and recent best-practice PRs/commits.
• Decisions made along the way:
  • Initial draft was one large SKILL.md with citation tables. User
    pushed back: example files age quickly. Refactored into a slim
    router + per-JTBD references each carrying the why.
  • User asked whether references cited back to PRs. They didn't.
    Added ## History sections to two references (the ones where PR
    history adds real teaching context — patterns banned because real
    code went wrong) rather than sprinkling PR links everywhere.
  • Followed the existing convention from using-kea-disposables /
    making-scenes-tab-aware: skill lives in .agents/skills/, not
    products/*/skills/, since it's a repo-local convention skill not
    a customer-facing PostHog AI skill.
• Verified all seven cited PR numbers exist and are MERGED before
  including them.

---

Created with PostHog Code

[pauldambra]

• chore(skills): add writing-kea-logics skill #58707 👈 (View in Graphite)
• master

This stack of pull requests is managed by Graphite. Learn more about stacking.

[greptile-apps]

Comments Outside Diff (1)

1. .agents/skills/writing-kea-logics/references/anti-patterns.md, line 362-364 (link)

   Incorrect JS comment — '' is falsy, not truthy

   The inline comment // '' is truthy! is factually wrong: in JavaScript Boolean('') is false, so empty string is falsy. The real reason '' still registers as an error in kea-forms is that the plugin checks error !== undefined (i.e. existence, not truthiness) — any non-undefined value in the errors map is treated as a present error. Teaching the wrong reason could send engineers on a debugging detour when their mental model of the form's hasErrors flag doesn't match what they see at runtime.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: .agents/skills/writing-kea-logics/references/anti-patterns.md
   Line: 362-364
   
   Comment:
   **Incorrect JS comment — `''` is falsy, not truthy**
   
   The inline comment `// '' is truthy!` is factually wrong: in JavaScript `Boolean('')` is `false`, so empty string is falsy. The real reason `''` still registers as an error in kea-forms is that the plugin checks `error !== undefined` (i.e. existence, not truthiness) — any non-`undefined` value in the errors map is treated as a present error. Teaching the wrong reason could send engineers on a debugging detour when their mental model of the form's `hasErrors` flag doesn't match what they see at runtime.
   
   
   
   How can I resolve this? If you propose a fix, please make it concise.

Prompt To Fix All With AI

Fix the following 1 code review issue. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 1
.agents/skills/writing-kea-logics/references/anti-patterns.md:362-364
**Incorrect JS comment — `''` is falsy, not truthy**

The inline comment `// '' is truthy!` is factually wrong: in JavaScript `Boolean('')` is `false`, so empty string is falsy. The real reason `''` still registers as an error in kea-forms is that the plugin checks `error !== undefined` (i.e. existence, not truthiness) — any non-`undefined` value in the errors map is treated as a present error. Teaching the wrong reason could send engineers on a debugging detour when their mental model of the form's `hasErrors` flag doesn't match what they see at runtime.

```suggestion
errors: ({ email }) => ({ email: email ? '' : 'Required' }) // '' is not undefined — kea-forms treats it as a present error
```

_{Reviews (1): Last reviewed commit: "chore(skills): add writing-kea-logics sk..." | Re-trigger Greptile}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d1b81c8268

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Remove requirement to include key in keyed logic path

This section states that keyed logics must include the key in path or instances “collide in redux”, but path in Kea is metadata for debugging/typegen rather than instance identity, which is handled by key(...). Encoding this as a hard rule will push contributors/agents to rewrite valid keyed logics and can cause unnecessary state-key churn (e.g., persisted localStorage keys) without fixing any real collision bug.

Useful? React with 👍 / 👎.