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.
The body is an actionable, error-hardened guide whose value comes from concrete CLI commands, real failure signatures, and authoritative tables — its worst failure mode is duplication, not vagueness. Primary improvements are de-duplicating warnings between the dedicated sections and Common Pitfalls, trimming the Foundry-JS inline code that already lives in a reference file, and fixing or removing the dead use-cases references.
Suggestions
Consolidate each duplicated warning into one place: keep the dedicated callouts (manifest path/entrypoint, vite.config.js, --sockets, run-from-app-root, quoted params) and reduce their Common Pitfalls entries to one-line pointers, or vice versa — this alone would recover roughly 30 lines of the conciseness cost.
Cut the body's Foundry-JS section to the FalconApi connect/theme contract plus one example per capability, and move the full collections/workflows/cloud-functions/LogScale snippets into references/foundry-js.md, which the Reading Guide already designates for that content.
Remove or create the missing use-cases/detection-enrichment.md and use-cases/first-app.md files cited under 'Use Cases' — dead references undermine the otherwise clean one-level-deep navigation scored by progressive disclosure.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is high-value and non-obvious throughout (sandbox quirks, EOF-hanging interactive pickers, `got string want integer` failure modes), but five warnings are each stated twice — the vite.config.js and manifest-path prohibitions, the `--sockets` requirement, the cd-back-to-root rule, and the quoted-params pitfall all appear both in dedicated sections and again in Common Pitfalls. The Foundry-JS section also inlines full collections/workflows/cloud-functions/LogScale code that the Reading Guide maps to references/foundry-js.md, so the body could be tightened well beyond minor trimming. This fits anchor 3 ('could be tightened') better than anchor 4's 'minor instances'. | 3 / 5 |
Actionability | Everything is copy-paste ready: exact CLI invocations with required flags ("foundry ui extensions create ... --sockets \"activity.detections.details\" --no-prompt"), runnable JS/TS snippets, the authoritative socket-ID table, and verbatim error strings to match against. Anti-drift check: anchor 4's 'minor gaps' does not apply — examples cover the common cases across pages, extensions, and both build/no-build templates. | 5 / 5 |
Workflow Clarity | The sequence is discernible (scaffold with --no-prompt → separate navigation add → npm install/build → cd back to app root → validate → deploy backend before `foundry ui run`) and pitfalls double as error-recovery guidance (e.g., revert vite.config.js on entrypoint deploy errors). It falls short of anchor 5 because there is no single ordered walkthrough with explicit validation checkpoints — `foundry apps validate` appears only in passing inside a pitfall, and scaffolding order is delegated to the development-workflow skill. | 4 / 5 |
Progressive Disclosure | Structure is good: all eight references/*.md files exist, are one level deep, and are well signaled via the Reading Guide task table. It misses anchor 5 because the body cites use-cases/detection-enrichment.md and use-cases/first-app.md which do not exist in the bundle, and the inlined Foundry-JS API examples duplicate content already placed in references/foundry-js.md. | 4 / 5 |
Total | 16 / 20 Passed |