Content
75%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
An actionable, well-organized reference: commands and config snippets are executable, critical gotchas (atomic deploys, no rollbacks, netlify.toml env vars, template-root reads) are explicit, and the bundle references are real and well-signaled. The main cost is token duplication — the house-rules section repeats body guidance — plus a missing verification checkpoint around permanent deploy deletion and post-deploy confirmation.
Suggestions
De-duplicate the "Netlify house rules" section against the body — rollback, secrets-scanning, .gitignore, manual --prod, and template-root rules each appear twice; keep one copy (or move the house rules to a referenced file) to recover ~35 lines.
Add explicit validation checkpoints for the destructive flows: confirm in the Deploys tab that a deploy published before reporting success, and confirm intent before permanent deploy deletion (which cannot be undone).
Strip non-operational meta text from the rendered body (the ctx-gen merge comment, the retention-inconsistency HTML comment, and the 'State this limitation explicitly' authoring instruction).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and non-obvious throughout (atomic deploys, 54,000-files-per-directory limit, skew-protection carve-outs), but the ~35-line "Netlify house rules" section restates guidance already present in the body (no rollback, secrets scanning, .gitignore warning, manual --prod warning, template-root rule), and meta lines like "State this limitation explicitly rather than leaving it implied" and the retention HTML comment add tokens without operational value. This is more than the 'minor instances that could be trimmed' of a 4, but well short of the padding of a 2. | 3 / 5 |
Actionability | Guidance is fully executable: copy-paste-ready `netlify deploy` / `netlify deploy --prod` commands, a complete netlify.toml context snippet (including the double-bracket plugin gotcha and quoted branch names), a working Deploy-to-Netlify markdown button with concrete URL variants, exact skip markers (`[skip ci]` in PR title vs commit message), and dashboard paths like "Deploys list > Lock to stop auto publishing". Specific examples cover the common cases. | 5 / 5 |
Workflow Clarity | Multi-step flows are sequenced clearly with checkpoints in the important places — the failed-deploy recovery flow ("A failed deploy never publishes" → check the "Why did it fail?" diagnosis → fix forward by reverting the commit), the entry-path flow (add `@netlify /path` to the PR, push a commit to regenerate), and the warning checkpoint before manual `netlify deploy --prod` on a Git-CD site. It is not a 5 because there is no explicit verify step after destructive-ish actions (e.g., confirming a deploy is published before declaring success, or a validation gate before the permanent, undeletable deploy deletion), which is a minor validation gap. | 4 / 5 |
Progressive Disclosure | The body stays an overview and pushes depth to three real, one-level-deep bundle files, each clearly signaled at the relevant point ("See references/netlify-toml.md for the full context precedence rules", "See references/cli-commands.md for the full CLI surface and flags", "references/deployment-patterns.md for context strategy") — all of which exist. It is not a 5 because the 35-line inline house-rules block is content that would sit better in its own referenced file, and the inlined secrets-scanning/rollback rationale is long enough that the split is not quite 'appropriate' throughout. | 4 / 5 |
Total | 16 / 20 Passed |