docs(plan-reviews): add Execution-settings recommendation preamble#1229
docs(plan-reviews): add Execution-settings recommendation preamble#1229shanbhagp wants to merge 1 commit intogarrytan:mainfrom
Conversation
…w and plan-eng-review
Adds a brief "Execution settings recommendation" blockquote at the top
of each skill's prompt body so users pick the right compute tier for
the task before invoking the skill.
The wording is intentionally task-shape framing ("bounded strategic
review", "second-tier compute (e.g., Opus Extra high)") rather than
pinned model names, so the guidance survives model-version changes.
Both templates and the regenerated rendered docs are included; CI's
skill-docs freshness check passes locally.
|
One observation that came up while writing this PR — surfacing it here as an offer rather than expanding scope: The same shape of guidance probably belongs on most of the bounded review skills ( I noticed you already have
No need to decide now; flagging in case it's useful context for review. |
What
Adds a short Execution settings recommendation blockquote at the top of
/plan-ceo-reviewand/plan-eng-reviewso users pick the right compute tier before invoking the skill.Why
Claude Code now exposes meaningfully different compute tiers (Opus Max, Opus Extra high, Sonnet, etc.). Some skills genuinely benefit from the top tier; many are bounded enough that mid-tier handles them at a fraction of the cost. Without per-skill guidance, users either over-spend on routine reviews or under-spend on review tasks that need headroom.
Wording is task-shape framing ("bounded strategic review", "second-tier compute (e.g., Opus Extra high)") rather than pinned model names, so the guidance survives model-version churn (Opus 4.7 → 4.8 → 5 etc.) without doc maintenance.
The pattern was developed across a set of project-local skills (six narrative-deck skills with similarly-shaped recommendations); the eng + CEO plan reviews were the natural upstream candidates — stable, non-domain-specific, and used widely.
Files
plan-ceo-review/SKILL.md.tmpl— preamble after H1, before## Philosophyplan-eng-review/SKILL.md.tmpl— preamble after H1, before "Review this plan thoroughly..."plan-ceo-review/SKILL.mdandplan-eng-review/SKILL.md— regenerated viabun run gen:skill-docs(all three hosts: Claude, Codex, Factory)Diff is purely additive: 4 files, +26 lines.
Reviewer notes
bun run gen:skill-docs && git diff --exit-codeis clean.skill-docs.ymlworkflow lands green on first build.version-gate.ymltrigger —VERSION/CHANGELOG.md/package.jsonuntouched. Happy to bump if your release cadence wants this in a versioned drop.{{PREAMBLE}}macro space).Aside (separate issue, not this PR)
While regenerating on Windows I noticed the repo has no
.gitattributes, so on Windows clones withcore.autocrlf=true(the default),bun run gen:skill-docsproduces CRLF-line files wheretransformFrontmatter()'s strip regex^${field}:\s*.*\nfails to match —sensitive: trueleaks through into ClaudeSKILL.mdoutputs. Worked around it locally by settingcore.autocrlf=false. Happy to file a separate issue or send a tiny fix PR (a one-line.gitattributeswould close it).