Skip to content

docs(seer): Fix stale paths and add the stories step to the seer-embed skill - #123910

Open
billyvg wants to merge 1 commit into
masterfrom
billyvong/fix-stale-seer-embed-skill
Open

docs(seer): Fix stale paths and add the stories step to the seer-embed skill#123910
billyvg wants to merge 1 commit into
masterfrom
billyvong/fix-stale-seer-embed-skill

Conversation

@billyvg

@billyvg billyvg commented Sep 9, 2026

Copy link
Copy Markdown
Member

Three things in .agents/skills/seer-embed/SKILL.md no longer match the tree. All three surfaced while auditing a new embed against the skill.

Stale test-util paths (Step 2b)

The skill sends you to embeds/testUtils.tsx for renderEmbed / hrefFor, and says to keep link-level cases in resourceEmbeds.spec.tsx. Neither file exists. The helpers are renderEmbed / getEmbedLinkHref, exported from embeds/components/resourceEmbedTestUtils.tsx.

Since no shared spec file is left either, the rule keeps only the half that still means something: colocate the spec, and don't start a new shared one.

The examples bullet describes an older stories page

It says all examples are "composed into a single markdown block and rendered through one <SeerMarkdown>". EmbedStory now renders one demo per example, and a single demo already shows the tag at every level the schema declares — so "use multiple examples to show block vs inline" is advice for a page that no longer exists.

The bullet now also states what level actually costs, which nothing recorded before:

  • codegen strips it, so it never reaches the LLM — it is a stories-page marker only;
  • the shared <EmbedStory> fallback reads it as licence to relabel the example to the embed's name and drop any later example with identical data. A redundant level therefore collapses several examples into same-named ones.

Nothing covered the stories page at all (new Step 5)

Every embed lands a section in seerMarkdown.mdx, and the skill never mentioned it. Worse, the obvious thing to write — <EmbedStory name="…" /> — is actively wrong for any embed that fetches by ID: the IDs in examples are invented for the LLM prompt, so nothing resolves them, the block renders its error state, and the page documents nothing.

The new step covers the live-data story pattern the fetching embeds (replay, trace, savedQuery, savedIssueView, alert, monitor) already share: query the viewer's own organization for a real resource and feed its ID to EmbedVariant. It records the two rules that are easy to get wrong — one EmbedVariant renders every declared level, so vary by prop combination rather than by level; and all four states (pending, error, empty, loaded) have to render, because stories run against whatever org the viewer happens to be in.

Testing

Docs only — no code changes. prek run passes on the file.

…d skill

Three things in the skill no longer match the tree, all found while auditing a
new embed against it.

Step 2b sends you to `embeds/testUtils.tsx` for `renderEmbed` / `hrefFor`, and
tells you to keep link-level cases in `resourceEmbeds.spec.tsx`. Neither file
exists. The helpers are `renderEmbed` / `getEmbedLinkHref` in
`embeds/components/resourceEmbedTestUtils.tsx`, and since no shared spec is
left, the rule keeps only the part that still means something: colocate, and
don't start a new shared file.

The `examples` bullet describes a stories page that composed every example into
one markdown block behind a single `<SeerMarkdown>`. `EmbedStory` now renders
one demo per example, and a single demo already shows the tag at every level
the schema declares -- so "use multiple examples to show block vs inline" is
advice for a page that no longer exists. The bullet also now says what `level`
actually costs: codegen strips it, so it never reaches the LLM, but the shared
fallback reads it as licence to relabel the example to the embed's name and
drop later examples with identical `data`.

Nothing at all covered the stories page, though every embed lands a section in
`seerMarkdown.mdx`, and the `<EmbedStory name>` fallback is actively wrong for
any embed that fetches by ID -- the IDs in `examples` are invented for the LLM
prompt, so the block renders its error state and the page documents nothing.
That is now Step 5, with the live-data story pattern the fetching embeds
already share, the four states such a story has to handle, and a pointer to the
smallest existing examples.

Claude-Session: https://claude.ai/code/session_016YUmhMZLo8geXJa93daPEQ
@billyvg
billyvg marked this pull request as ready for review September 9, 2026 16:23
@billyvg
billyvg requested a review from natemoo-re September 9, 2026 16:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant