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.
This is a strong, highly actionable instruction skill: nearly every section carries codebase-specific rules, exact code patterns, and validation gates (screenshot parity, per-micro-commit builds, a closing audit checklist) rather than generic explanations. Its weaknesses are mild — some duplication between the audit checklist and earlier sections, a few patterns described without examples, an implicit process entry point, and a monolithic single-file layout despite depending on external docs.
Suggestions
Add short code snippets for the two patterns currently described only in prose — the async placeholder-then-render flow (Section 8) and a parameterized fragment factory returning LitTemplate (Section 9).
Deduplicate the Mental Audit checklist against Sections 3, 10, 11, and 13, or reframe it as page-cross-references (e.g., 're-check named imports, Section 3') to reclaim tokens.
Open with a 3-5 line overview stating the entry point (which files/signal starts Pass 2) and the expected end state, so the 17 sections read as an explicit sequence rather than a rule compendium.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The ~240-line body is dense with project-specific constraints Claude cannot know (named-import policy, clang-format off boundaries, Gerrit moved-block behavior, widget() directive forms, WrapperWidget display:contents caveat) with almost no padding or explanation of known concepts. It falls short of 5 because the Mental Audit section repeats items already covered in Sections 3, 10, 11, and 13, and a few rules are stated twice (e.g., the Section 4 read-first requirement restated in Section 7), so minor trimming is possible. | 4 / 5 |
Actionability | Most guidance is directly executable: the exact import line from '../../ui/lit/lit.js', 'render(this.template(), this.containerField as HTMLElement);', exact CSS ('flex: auto; height: 100%;'), exact bindings like '.data=${{variant: Buttons.Button.Variant.OUTLINED}}' and 'show=${!input.isTraceApp && input.isSidebarOpen ? 'both' : 'main'}', plus concrete component mappings. It stops short of 5 because some common patterns are described without any code (asynchronous render placeholders in Section 8, parameterized fragment factories in Section 9) and there is no complete worked example. | 4 / 5 |
Workflow Clarity | The 17 numbered sections give a logical progression, and validation is explicit and repeated: zero-tolerance screenshot diffs (Section 10), build-and-test after each micro-commit (Section 16), a user-confirmation pause (Section 17), and a 7-question self-audit checklist including 'Does the code compile and do visual tests pass with 0% diff?'. It is not a 5 because the workflow's entry point is implicit (no step identifying target files or how this pass is kicked off — it assumes orchestrator context), and error-recovery beyond 'must be resolved before proceeding' is not elaborated. | 4 / 5 |
Progressive Disclosure | The body is well structured with numbered, titled sections, and its two external references are clearly signaled one level deep with purpose and a MANDATORY flag ([ui_engineering.md](../../../docs/ui_engineering.md) and the no-imperative-dom-api.ts migration script); no bundle files exist to nest. It misses 5 because no SKILL.md-level overview or split exists — all ~240 lines, including detailed subsystem recipes (ListWidget migration paths, WrapperWidget rules, split-view guidelines) that could live in reference files, are inlined in one document. | 4 / 5 |
Total | 16 / 20 Passed |