Content
86%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-crafted, token-efficient body that clearly organizes the doc lifecycle, per-folder rules, agent behaviors, and workflow routing with lean prose and good progressive disclosure to sibling skills and templates. The two dimensions at 4 reflect minor, not structural, gaps: unlisted template names and absent explicit validation checkpoints.
Suggestions
Name the template identifiers for proposals, decisions, and postmortems (e.g. alongside the guide/onboarding-guide/runbook mentions) so the write({ document: { path, template } }) call is fully copy-paste ready.
Add one explicit validation checkpoint to the lifecycle flow (e.g. confirm status transitions are recorded in frontmatter before a proposal graduates to a decision) to tighten workflow clarity.
Consider naming the exact status-transition command or steps for superseding a decision, since only the Supersedes: linking convention is given.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean: a compact flow diagram, one dense paragraph per folder, and a routing table; shape references ('MADR / Nygard shape', 'Google SRE shape', 'Diátaxis') assume competence instead of explaining it. Every section earns its place. | 5 / 5 |
Actionability | Concrete guidance throughout — file naming ('0001-feature-name.md'), status flows ('draft → fcp → accepted/rejected'), section shapes, the write({ document: { path, template } }) call, and threshold-based agent behaviors ('status: draft more than 14 days'). Minor gaps: exact template names for proposals, decisions, and postmortems are not listed. | 4 / 5 |
Workflow Clarity | The lifecycle sequence is clearly diagrammed with explicit transitions ('↓ accepted', '↓ derived', '↓ when things break') and the table routes each task type to a skill, but there are no explicit validation checkpoints, keeping it below the top anchor. | 4 / 5 |
Progressive Disclosure | At under 50 lines with well-organized sections, the body stays an overview and delegates detail exactly one level deep — sibling workflow skills in the table and templates in the closing section — making navigation easy. | 5 / 5 |
Total | 18 / 20 Passed |