Content
71%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.
A well-structured, expert-level overview with genuine progressive disclosure — every reference path is real, one level deep, and clearly scoped — and unusually concrete guidance (exact APIs, commands, file layout, decision table). The main cost is token efficiency: several rules are stated two to five times across Quick Start, General Rules, and Anti-Patterns, and the body could be trimmed meaningfully without losing information.
Suggestions
State each rule once: consolidate the sidebar-row/custom-background guidance (repeated across General Rules lines 65-70 and three anti-pattern bullets) and the 30-char MenuBarExtra cap (lines 63 and 110) into single canonical statements.
Merge the 'Pre-Edit Checklist' into the 'Workflow For A New macOS Scene Or View' as its early steps, since the two sequences currently overlap and compete.
Trim the duplicated no-hardcoded-white rule (lines 28, 65, and 112) to one General Rules entry plus one anti-pattern reference.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body contains almost no filler — every line is non-obvious expert guidance (e.g. the `WindowGroup(..., id:)` vs `Window(...)` launch distinction, the 30-char menu item cap) — but the same rules are restated repeatedly: sidebar/custom-background guidance appears in General Rules twice (lines 65-66 and 70) and again as three separate anti-patterns, the 30-char MenuBarExtra rule appears at lines 63 and 110, the Window/WindowGroup rule at lines 22 and 109, and the no-hardcoded-white rule at lines 28, 65, and 112. That is 'mostly efficient but could be tightened' (3) rather than noticeably padded (2) because the duplicated material is dense guidance, not explanation of concepts Claude already knows. | 3 / 5 |
Actionability | Guidance is highly concrete and executable: exact shell commands (`git rev-parse --is-inside-work-tree`), exact API calls (`NSApp.setActivationPolicy(.regular)`, `@SceneStorage`, `@AppStorage`), a prescriptive file tree (`App/`, `Views/`, `Models/`, `Stores/`, `Services/`, `Support/`), a precise 50-line single-file threshold, and a lookup table mapping state scenarios to specific wrappers. It falls short of fully copy-paste-ready (5) because it defers to external skills not in the bundle ('use the exact bootstrap contract from the `macos-build-run-debug` skill') and offers no inline code snippet, relying on the reference files for examples. | 4 / 5 |
Workflow Clarity | There is a clear 7-step 'Workflow For A New macOS Scene Or View' that ends with explicit validation ('Validate the flow with a build and a quick usability pass: multiwindow assumptions, settings entry points, and selection stability'), plus a Pre-Edit Checklist that front-loads sequencing. This is 'clear sequence with most checkpoints present' (4) rather than 5 because there is no error-recovery loop around the build step (what to do when the build fails) and the two quick-start tracks are partially overlapping with the workflow and checklist rather than one canonical sequence. | 4 / 5 |
Progressive Disclosure | The body is a true overview: all six referenced files exist in the bundle, each is listed in 'Cross-Cutting References' with a one-line scope description, navigation is one level deep, and a designated entry point (`references/components-index.md`) is named both in Quick Start and in a dedicated section. Detail (code examples, per-component guidance) is pushed into the reference files, and the inline material (rules, table, anti-patterns) is appropriately overview-level, matching the top anchor. | 5 / 5 |
Total | 16 / 20 Passed |