I noticed a gap in the industry: teams were either reviewing specs manually — inconsistent and unscalable — or delegating to LLMs that produce different feedback every time. Neither approach gives you a reproducible quality baseline.

Requirements engineering has 40+ years of proven research — IEEE 830, ISO 29148, readability formulas (Flesch, Gunning Fog), cognitive load theory. We took that body of work and made it operational as a CLI tool.

`understanding` scores specs across 6 categories using 31 metrics: - Structure (30%) — atomicity, passive voice, pronouns - Testability (20%) — quantifiable constraints, boundary coverage - Readability (15%) — six classical formulas - Cognitive (15%) — sentence complexity, negation load - Semantic (10%) — actor/action/object presence - Behavioral (10%) — scenarios, state transitions

Same input always gives the same output. Runs in ~500ms. No cloud, no API keys, everything local.

There's also an experimental energy mode that uses a tiny local model (SmolLM2-135M, 270MB) to find ambiguity hotspots at the token level — a second pair of eyes beyond the rules. The idea is based on Hinton's energy framework: high-energy tokens are "surprising" to the model, which correlates with vague or oddly worded requirements.

Install: `uv tool install git+https://github.com/Testimonial/understanding.git --with "spacy>=3.0.0"`

Happy to discuss the metrics, the research foundations, or the case for deterministic analysis over probabilistic approaches.