Content
82%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.
The body is a well-structured, highly actionable CLI reference with concrete commands, a sequenced golden path, and clear error-recovery guidance. Its main limitation is the absence of progressive disclosure into separate reference files and a few sections that could be slightly tighter.
Suggestions
Split the dense "API preflight" and "Prompt template" sections into separate reference files linked from the overview to improve progressive disclosure.
Add an explicit validation checklist before API/browser runs (e.g., confirm consent, check `oracle doctor` output, verify file set via `--dry-run`) to strengthen workflow checkpoints.
Tighten the "Exhaustive prompt" pattern subsection, which partially restates guidance already covered in the Prompt template list.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and assumes Claude's competence (e.g., "Oracle starts with **zero** project knowledge"), with only minor sections like the "Exhaustive prompt" pattern that could be trimmed. | 4 / 5 |
Actionability | Provides copy-paste-ready commands throughout (e.g., `npx -y @steipete/oracle --engine browser --model gpt-5.5-pro -p "<task>" --file "src/**"`) covering the common browser, API, dry-run, and reattach cases. | 5 / 5 |
Workflow Clarity | A numbered "Golden path" sequences the work with a preview checkpoint (`--dry-run` + `--files-report`) and a reattach feedback loop for detached runs, though some validation guidance is implicit rather than an explicit checklist. | 4 / 5 |
Progressive Disclosure | Well-organized into clearly signaled sections (Commands, Attaching files, Engines, API preflight, Sessions); no external reference files exist, and dense subsections like API preflight are inlined but appropriately placed with minor organization gaps. | 4 / 5 |
Total | 17 / 20 Passed |