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.
A well-structured runbook body: clear lane separation, explicit routing to one-level-deep workflow files, a validated updater contract with backup and changelog safeguards, and exact acceptance commands. The main gaps are repetition across sections and the fact that the referenced workflow and tool files are not part of this package, leaving the core operational detail unverifiable.
Suggestions
Consolidate the repeated partial-failure/backup rules and the ReportTemplate-vs-dashboard caveats (currently restated in Workflow routing, Failure mode, Gotchas, and Expected artifacts) into a single section to tighten conciseness.
Add a minimal invocation example for Tools/UpdateTelos.ts (or fold it into Workflows/Update.md) so the personal-update lane is executable without guessing the tool's interface.
Move the long validation/acceptance command list into a referenced file (e.g. Workflows/Validation.md) or trim it to the changed-scope essentials, and ship the Workflows/ and Tools/ files referenced by the body so progressive-disclosure targets are verifiable.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is a dense, directive runbook with no explanations of concepts Claude already knows ("Never hand-edit a personal TELOS file. Use `Tools/UpdateTelos.ts`, which must: 1. validate the requested file; 2. create a timestamped pre-change backup..."). It is not 5 because backup/changelog partial-failure rules and the ReportTemplate/no-dashboard caveat are each repeated across sections and the validation section runs long, and not 3 because nearly every line is actionable instruction without padding. | 4 / 5 |
Actionability | Concrete commands and paths are given ("python3 -m unittest -v Skills/product-strategy/telos/Tools/test_update_telos.py", "./bin/ask skills audit Skills/product-strategy/telos --level compat --json --robot", "git diff --check -- Skills/product-strategy/telos") alongside explicit routing ("read [Workflows/Update.md](Workflows/Update.md)"). It is not 5 because the core update mechanics and how to invoke Tools/UpdateTelos.ts are deferred to workflow/tool files not included in this package, and not 3 because specific commands, artifacts, and acceptance criteria are spelled out. | 4 / 5 |
Workflow Clarity | The sequence is clear with explicit validation checkpoints and feedback loops: the updater's five-step contract ("stop without writing when validation or backup creation fails"), the Failure mode section, and "After a partial failure, report whether a backup, target write, or changelog entry occurred." Destructive-write validation is present, so the workflow-clarity cap does not apply. It is not 5 because the internal sequences of each routed workflow (Update, InterviewExtraction, CreateNarrativePoints, WriteReport) are not visible in SKILL.md itself. | 4 / 5 |
Progressive Disclosure | References are well-signaled and one level deep ("Load only the selected workflow" plus four explicit Workflows/*.md links and a See Also table). It is not 5 because none of the referenced files (Workflows/, Tools/UpdateTelos.ts, Tools/LifeosConfig.ts, ReportTemplate) ship with the package so the navigation target cannot be verified, and the inlined validation/acceptance detail is long enough that it could live in a separate file; not 3 because the structure and signaling within SKILL.md are clear. | 4 / 5 |
Total | 16 / 20 Passed |