Content
71%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 lean, rule-dense body with concrete file paths, commands, and an acceptance bar that doubles as validation — genuinely actionable for a compiler maintainer. The main defects are a dangling `regex.md` reference with no bundle file behind it and the absence of any implementation example to bridge 'inspect the seams' to 'write the code'.
Suggestions
Fix the dangling reference in the Session validation section: either add `references/regex.md` with the UTF-16/pattern-invariant details it promises, or remove/replace the `regex.md` mention with the inline facts actually needed.
Tighten the long compound bullets in Backend Implementation Rules (e.g. the placeholder-body enumeration and the conformance-coverage bullet) into shorter, separate rules so each constraint is scannable.
Add a brief registration example (or a pointer to a concrete existing target) showing what a target registration and emitter stub look like, so the touchpoint list translates directly into a first edit.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Dense, rule-list format with no padding and no explanation of concepts Claude already knows — every bullet is repo-specific policy. Not a 5 because several bullets are over-stuffed compound sentences (e.g. "Concrete public generated methods must never be placeholder-only bodies such as `pass`, `return None`, `return nil`, `Value::Null`, empty vectors, or generic 'not implemented'/'unsupported' fallbacks") that could be tightened. | 4 / 5 |
Actionability | Highly concrete guidance: exact file paths (`tools/axir/internal/axir/codegen.go`, `axir_test.go`, `scripts/run-example.mjs`), copy-paste verification commands (`npm run test:axir`, `axir verify --targets python,java,cpp,<new-target>`), and named suites and doc locations. Not a 5 because the implementation path itself is never shown — no snippet or template of what target registration or an emitter actually looks like, leaving minor gaps between 'inspect these seams' and 'do it this way'. | 4 / 5 |
Workflow Clarity | Clear logical sequence via section order (First Checks → Implementation Rules → Required Touchpoints → Acceptance Bar → Avoid) with an explicit Acceptance Bar serving as validation checkpoints (test:axir, axir verify, generated-output audits). Not a 5 because the sequence is unnumbered and there is no explicit fix-and-re-run feedback loop; error recovery is only implied by the Avoid section. | 4 / 5 |
Progressive Disclosure | Sections are well-organized and appropriately sized, but the body references "see `regex.md`" (Session validation section) and no such file exists — no references/, scripts/, or assets/ directories are present in the bundle, so this is a dangling pointer. The reference is also buried inline in prose without a link or dedicated section. Not a 4 because a cited reference file that does not exist is a navigation failure, not a minor organization gap; not a 2 because the overall structure is otherwise sound. | 3 / 5 |
Total | 15 / 20 Passed |