Content
85%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The body is a well-structured, highly actionable overview: tight mental model, executable commands, explicit agent safety rules with validation, and clean progressive disclosure to a verified reference bundle. The only weakness is a time-sensitive version pin and minor redundancy between the Agent Rules and Common Mistakes tables.
Suggestions
Move the "Target version: jj 0.36+" pin into a dedicated compatibility/version section or remove it, since time-sensitive version numbers penalize conciseness when placed outside a deprecated/old-patterns section.
Consolidate the Agent Rules and Common Mistakes tables — they overlap (e.g., missing -m, unquoted revsets, un-set bookmarks) — to remove redundancy and tighten the token budget.
Consider pulling the most critical single recovery command (jj undo) into the Core Workflow so the daily loop visibly includes an escape hatch for failed mutations.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly lean and avoids explaining concepts Claude already knows, but pins a time-sensitive version ("Target version: jj 0.36+") outside any deprecated section, and the Common Mistakes table overlaps somewhat with the Agent Rules, so it could be tightened. | 2 / 3 |
Actionability | Concrete, copy-paste-ready commands throughout (jj describe -m, jj new -m, jj squash, jj bookmark set feat -r @, jj git push -b feat) plus an executable TOML config block provide fully executable guidance. | 3 / 3 |
Workflow Clarity | The Core Workflow gives a clear describe -> code -> new -> repeat loop, and Agent Rule 3 ("Verify after mutations. Run jj st after squash, abandon, rebase...") plus the Recovery section provide explicit validation checkpoints and undo feedback loops for destructive ops. | 3 / 3 |
Progressive Disclosure | A Topics table maps needs to one-level-deep deep-dive references, and a Reference Index organizes them by category; all referenced files (bookmarks.md, revsets.md, conflicts.md, etc.) exist in references/, so navigation is clear and well-signaled. | 3 / 3 |
Total | 11 / 12 Passed |