docs(seer): Fix stale paths and add the stories step to the seer-embed skill - #123910
Open
billyvg wants to merge 1 commit into
Open
docs(seer): Fix stale paths and add the stories step to the seer-embed skill#123910billyvg wants to merge 1 commit into
billyvg wants to merge 1 commit into
Conversation
…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
marked this pull request as ready for review
September 9, 2026 16:23
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Three things in
.agents/skills/seer-embed/SKILL.mdno 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.tsxforrenderEmbed/hrefFor, and says to keep link-level cases inresourceEmbeds.spec.tsx. Neither file exists. The helpers arerenderEmbed/getEmbedLinkHref, exported fromembeds/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
examplesbullet describes an older stories pageIt says all examples are "composed into a single markdown block and rendered through one
<SeerMarkdown>".EmbedStorynow 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
levelactually costs, which nothing recorded before:<EmbedStory>fallback reads it as licence to relabel the example to the embed's name and drop any later example with identicaldata. A redundantleveltherefore 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 inexamplesare 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 toEmbedVariant. It records the two rules that are easy to get wrong — oneEmbedVariantrenders 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 runpasses on the file.