Skip to content

fix(help): describe the content model in the root help - #286

Open
angeloashmore wants to merge 4 commits into
mainfrom
claude/github-issue-review-xvb6g3
Open

fix(help): describe the content model in the root help#286
angeloashmore wants to merge 4 commits into
mainfrom
claude/github-issue-review-xvb6g3

Conversation

@angeloashmore

@angeloashmore angeloashmore commented Sep 4, 2026

Copy link
Copy Markdown
Member

Resolves: #274

Description

The CLI never says what a Prismic model is made of. An agent asked to model a blog post adds a key text field named author, even when the project has an author type. The reader gets a name in a string instead of a link to a document.

The root help now has a MODELING section. It states the shape of a model, names the content relationship as the way a page uses another type, and points to prismic docs view content-modeling for the rest. The plan on #274 also asked for a line after prismic type create. This PR leaves it out, because #283 added the same shape of line and then removed it.

The author is a content relationship in 14 of 15 trials, against 3 of 5 on main. The other evals held.

Checklist

  • If my changes require tests, I added them.
  • If my changes affect backward compatibility, it has been discussed.
  • If my changes require an update to the CONTRIBUTING.md guide, I updated it.

Preview

$ prismic --help
...
MODELING
  Pages are page types, built from slices and fields. Content that is
  not a page is a custom type, such as an author or a navigation menu.
  A page references a custom type with a content relationship field,
  instead of repeating its content.
  Run `prismic type list` to see what a project has, and
  `prismic docs view content-modeling` for details.

How to QA 1

$ node --run build
$ node dist/index.mjs --help
$ EVAL_TRIALS=5 PRISMIC_ALLOW_EVALS=true node --run evals -- \
    evals/design-sensible-models.eval.ts evals/check-before-acting.eval.ts

🤖 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 to prismic type list and prismic docs view content-modeling.

The --help integration 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

  1. Please use these labels when submitting a review:
    ❓ #ask: Ask a question.
    💡 #idea: Suggest an idea.
    ⚠️ #issue: Strongly suggest a change.
    🎉 #nice: Share a compliment.

@claude claude Bot deleted a comment from angeloashmore Sep 4, 2026
@claude claude Bot deleted a comment from angeloashmore Sep 4, 2026
@claude claude Bot deleted a comment from angeloashmore Sep 4, 2026
@angeloashmore
angeloashmore marked this pull request as ready for review September 5, 2026 03:33
@angeloashmore angeloashmore changed the title fix(help): tell agents to reuse existing types with a content relationship fix(help): describe the content model in the root help Sep 5, 2026
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
angeloashmore force-pushed the claude/github-issue-review-xvb6g3 branch from 11c3e1a to 16703dc Compare September 5, 2026 03:36
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.

evals: agent models the author of a blog post as key text

2 participants