Content
82%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.
The body is a dense, high-signal planning skill: concrete commands, decided architecture constraints, and strong safety stop-conditions for a database cutover domain, with detail appropriately deferred to canonical repo documents. The main gaps are the externalized migration/cutover execution steps, error recovery expressed only as stop/freeze directives, and unverifiable deep relative links.
Suggestions
Inline the entry command (or a one-line summary) of the migration/cutover workflow from the external postgresql.md doc so the critical path is executable without leaving the skill.
Add an explicit failure-recovery loop after step 5 (e.g., "If `pnpm pg:check` or behavior checks fail: fix, then re-run before proceeding") to complement the stop/freeze directives.
Verify the `../../../developing/...` relative links resolve from the skill's installed location, or mirror the two referenced docs as bundled references/ files so navigation does not depend on repo layout.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Every line carries project-specific constraints Claude could not infer ("Pass `--org amplft` explicitly", "Application Hyperdrive caching is disabled", "Migrations and backup tools use the direct TLS endpoint on port 5432", "Keep PostgreSQL baseline/migrations under `packages/db/postgresql/migrations`"). There is no tutorial filler or explanation of concepts Claude already knows; the date (2026-10-04 cutover) and version (PostgreSQL 18) state decided baselines rather than time-conditional instructions. Not 4: there is no padding left to trim. | 5 / 5 |
Actionability | The "Shortest useful start" gives concrete, copy-paste-ready commands and paths (`pnpm pg plan`, `tooling/postgresql/resources.json`, `pnpm pg:check`, `pnpm staging:deploy`) plus specific file locations. It is not anchor 5 because execution details for migrations and cutover are deliberately deferred to an external workflow doc, and planning steps like "Define who writes each fact and which readers need a transaction" are unavoidably abstract; it clearly exceeds anchor 3's pseudocode-level guidance. | 4 / 5 |
Workflow Clarity | A clear 5-step sequence ends in explicit validation ("Run `pnpm pg:check`... add the smallest real PostgreSQL behavior checks"), and the cutover section lists checkpoint items (checksums, lock ownership, runtime grants, restore evidence) plus explicit stop conditions ("Stop the affected operation on a mismatched environment/branch, unknown owner, applied migration drift, failed restore..."). It is not anchor 5 because error recovery is expressed only as stop/freeze directives with no in-file fix-and-revalidate loop, and the detailed checklist is external; it is well above anchor 3, whose checkpoints are missing or implicit. | 4 / 5 |
Progressive Disclosure | Sections are well organized (Shortest useful start, Decisions that change implementation, Before applying or cutting over), with clearly signaled one-level-deep pointers to canonical docs ("Read [physical database ownership](../../../developing/architecture/physical-db-split.md)") and deliberate deferral ("Use the workflow's migration and cutover checklist rather than copying it here"). No bundle files (references/, scripts/, assets/) exist, and the deep relative links point outside the skill bundle where they cannot be verified — a minor organization gap that keeps it below anchor 5. | 4 / 5 |
Total | 17 / 20 Passed |