fix(help): describe the content model in the root help - #286
Merged
Merged
Conversation
angeloashmore
marked this pull request as ready for review
September 5, 2026 03:33
An agent asked to model a blog post with an author added a key text field named author, even though the project had an author type. The CLI never showed the agent what the project already had. Every trial that passed ran `prismic type list` on its own first. Every trial that failed did not. The root help has a MODELING section. It says to list the types and slices first, and to link to an existing type with a content relationship field instead of copying its data into text fields. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Xywd7QAoQLV7eyGpDvvtMN
The first wording told the agent to run `prismic type list` and `prismic slice list` before it models. Five trials of the vague design eval dropped to 1/5 and the page type eval to 3/5. Four of eleven failures were the agent reading the project and then stopping without a create command. Main does that in one of nine. The section now states the rule and names one command. The target eval holds at 19/20 over three runs. No eval ends in a survey with no create command over six failures. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Xywd7QAoQLV7eyGpDvvtMN
The section said a model can reuse a type. That is not what happens. A document references a document of another type, the way a blog post references its author. The section now says that. The section also repeated what the docs say. It now points to `prismic docs view fields/content-relationship` instead. Every eval in the file is at or above main over five trials. The vague design eval and the page type eval each moved from 3/5 to 5/5. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Xywd7QAoQLV7eyGpDvvtMN
The section carried one rule about references under a modeling heading. It read as copy for one case. It now states the shape of a Prismic model: pages are page types, everything else is a custom type, and a page references a custom type instead of repeating its content. A longer version named all four structures. The agent read the project and the docs and then stopped without a create command in three of five trials of the vague design eval. Breadth in the root help buys reading, not action. This version keeps the decision and drops the taxonomy. Over ten trials each: the page type eval is 8/10, the vague design eval 9/10, and the page and data eval 8/10. Main is 3/5, 3/5, and 5/5. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Xywd7QAoQLV7eyGpDvvtMN
angeloashmore
force-pushed
the
claude/github-issue-review-xvb6g3
branch
from
September 5, 2026 03:36
11c3e1a to
16703dc
Compare
lihbr
approved these changes
Sep 9, 2026
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.
Resolves: #274
Description
This PR ensures agents have correct knowledge of Prismic's modeling capabilities.
Our evals showed content relationships specifically as a weak point. Instead of linking an author document to a blog post, for example, the agent adds an "Author" key text field.
With this PR, the "models a page type with sensible field types" eval improves from 10/21 total passing runs to 14/15.
Checklist
Preview
How to QA 1
🤖 Generated with Claude Code
https://claude.ai/code/session_01Xywd7QAoQLV7eyGpDvvtMN
Note
Low Risk
Help text and a test assertion only; no runtime behavior or API changes.
Overview
Root
prismic --help(and default help) now includes a MODELING section alongside existing guidance like ROUTES. The new text explains that pages are page types built from slices and fields, that non-page content lives in custom types, and that pages should link to those types via content relationship fields rather than duplicating data. It also directs users toprismic type listandprismic docs view content-modeling.The
--helpintegration test is updated to assert MODELING appears in the output.Reviewed by Cursor Bugbot for commit 16703dc. Bugbot is set up for automated code reviews on this repo. Configure here.
Footnotes
Please use these labels when submitting a review:
⚠️ #issue: Strongly suggest a change.
❓ #ask: Ask a question.
💡 #idea: Suggest an idea.
🎉 #nice: Share a compliment. ↩