Comprehension rubric
A qualitative checklist for grading DTPR content (datachain-types, categories, elements, full datachain-instances) against the bar of "a non-technical person encountering an AI system understands this on a quick read." The audience is anyone meeting an AI system in the wild — in an app, on a website, in a vehicle, on a kiosk or sign, or while moving through public space — with enough time to parse what they see but no prior expertise. There is no scoring math. Each item has pass / fail / partial signals plus an explicit n/a when it does not apply to the artifact under review.
This rubric is the shared dependency of dtpr-comprehension-audit (standalone use) and the four authoring skills that inline findings — dtpr-datachain-structure, dtpr-category-audit, dtpr-element-design, and dtpr-translate — which emit a Comprehension check block using the shared template before handing off via schema:new.
The seven items
| Item | Passes when... |
|---|---|
| Audience fit | The language, framing, and example are understood by a non-expert on first read. |
| Plain-language | Every noun and verb is everyday English or glossed once with a plain-English anchor. |
| Symbol legibility | Silhouette is clear at sign scale; meaning carries even without caption. (n/a when the artifact has no symbol.) |
| Ambiguity flags | No ambiguities, or every ambiguity is explicitly flagged in the content. |
| Locale coverage | Every claim is translatable without idiom loss; placeholder syntax supports all required locales. |
| Variable-substitution clarity | Variable placeholders render cleanly across the expected value range. (n/a when the artifact has no variables.) |
| Overlap and distinctness | Adjacent items (elements within a category, categories within a datachain-type) occupy distinct semantic slots. (n/a when reviewing a single element with no peers.) |
A holistic Overall verdict closes the block. It does not average the items — if any item is fail and the artifact will ship publicly, Overall is fail. If every item is pass or n/a, Overall is pass. Otherwise partial with a one-line summary of what to fix.
Block template
Schema-tier skills copy this shape verbatim in their proposal output:
## Comprehension check
- **Audience fit:** pass|fail|partial|n/a — <one-line reason>
- **Plain-language:** pass|fail|partial|n/a — <one-line reason>
- **Symbol legibility:** pass|fail|partial|n/a — <one-line reason>
- **Ambiguity flags:** pass|fail|partial|n/a — <one-line reason>
- **Locale coverage:** pass|fail|partial|n/a — <one-line reason>
- **Variable-substitution clarity:** pass|fail|partial|n/a — <one-line reason>
- **Overlap and distinctness:** pass|fail|partial|n/a — <one-line reason>
- **Overall:** pass|fail|partial — <one-line summary>
Rubric version: <YYYY-MM-DD from comprehension-rubric.md frontmatter>
Rules
- One bullet per rubric item, in the order above. Do not reorder or skip items; mark inapplicable items n/a with a reason.
- The
<one-line reason>must name the specific phrase, element, or pattern that drove the verdict. "pass — reads cleanly" is not a reason; "pass — 'who sees your data' avoids jargon" is. - The
Rubric version:trailer carries therubric_versionfrom the rubric's frontmatter at the time of the audit. When the rubric evolves, prior audits remain interpretable — callers re-grade by re-running the skill.
Source
plugin/dtpr/references/comprehension-rubric.md— full rubric, source of truth: repository.plugin/dtpr/references/comprehension-block-template.md— template source.