The Spec score
One number from 0 to 100 for how ready your spec is to build from: what it checks, what holds it down, when it moves, and what to fix first.
What it measures
The Spec score sits on the project's Overview. It says how ready the spec is to build from: whether a developer or a coding agent could build what it describes without guessing. It is given once the project has been assessed: press Assess.
| Score | Band |
|---|---|
| 85 to 100 | Ready to build |
| 65 to 84 | Reviewable |
| 40 to 64 | Developing |
| 0 to 39 | Draft |
Six areas
The score is a weighted average of six areas. Each tile under Issues by area shows the area's share and opens its findings.
| Area | Checks | Weight |
|---|---|---|
| Requirements | Wording, acceptance criteria, rationale, priority | 30 |
| Stories | Wording, stakeholders, priority | 10 |
| Consistency | Conflicts, duplicates, terms used two ways | 10 |
| Traceability | Requirements linked to stories, stories to stakeholders | 20 |
| Quality attributes | Whether the qualities the product needs are covered | 20 |
| Interfaces | Contracts between subsystems, external systems named | 10 |
The default weights. Editors can change them under Weights; 0 switches an area off, with its caps, its fixes and its model calls.
Two sub-scores split the number. Checked is judged against the spec itself: every area but quality attributes. Estimated is quality attributes, which can only be estimated: whether the spec covers what the product needs.
What holds it down
Some gaps cap the score, whatever the rest looks like. Only facts the code checks set a cap, never a model's judgement. Most caps are graded: they reach full strength once the Must items affected weigh a quarter of the spec, and ease toward 100 with fewer. The subsystems cap is the exception: it holds at 70 for as long as a spec of more than 20 requirements is not split.
| Cap | At full strength |
|---|---|
| Must requirements without acceptance criteria | 60 |
| More than 20 requirements and no subsystems | 70 |
| Must stories with no system requirement | 75 |
| Open questions or placeholders on Must items | 84 |
When it moves
Two kinds of check make the score. Graph checks read the spec as it is: links, attributes, priorities, open questions, placeholders such as TBD. They follow every edit. Model checks read the wording, and are judged by a pinned model when you assess.
The score moves on Assess
An edited requirement keeps the verdict it had until the next Assess judges the new text. Until then the card says how many things changed since the last assessment.
Assess uses credits, like the other AI actions, and judges only what changed since the last run.
Next to fix
Up to five fixes, the largest gain first. Each comes with what to do about it:
- Suggest stories, when something is missing: Entalpa proposes stories that cover it, so the requirements that follow stay traced.
- Improve, when requirements exist but fall short: Analyze proposes rewrites for you to review.
- Review, when only you know the answer: a placeholder, a priority, a story's stakeholder.
What it does not score
- The project description. It is where a project starts, not what it becomes.
- A glossary.
- The category and risk of a requirement. They are worth writing, but no spec format asks for them, and a score that rewarded them would reward Entalpa's own output.
For experts: the standards behind the score
The Spec score is built on published requirements-engineering standards and research, and its rubric keeps the source next to every check. The two sub-scores follow a distinction from that research: internal completeness, whether a spec is whole in itself, which can be checked, and external completeness, whether it covers what the system needs, which can only be estimated (Zowghi and Gervasi, 2003). Checked and Estimated are those two.
| Area | What it checks | Based on |
|---|---|---|
| Requirements | No vague terms, escape clauses or open-ended lists. One obligation each. Verifiable, with its conditions stated. No absolutes that cannot be met. Free of design. Active voice, and no pronoun without its noun. Acceptance criteria that can be tested, a rationale, a priority. | ISO/IEC/IEEE 29148:2018, §5.2.5 (characteristics of individual requirements), §5.2.7 (requirement language criteria) and §5.2.8 (requirement attributes). The INCOSE Guide to Writing Requirements. Requirements smells (Femmer et al., 2017). |
| Stories | A role, a means and an end. One feature. A need, not a solution. One reading. A stakeholder the project defines. A priority. | The Quality User Story framework (Lucassen et al., 2016). INVEST (Wake, 2003). |
| Consistency | No requirements that conflict or repeat each other, terms used one way, and targets that can be met together. | ISO/IEC/IEEE 29148:2018, §5.2.6 (characteristics of a set of requirements). IEEE Std 830-1998, §4.3: consistent. The INCOSE guide on consistent terms and units. |
| Traceability | Every stakeholder has a story, every story a system requirement, every requirement a story, and every subsystem requirement a parent. | ISO/IEC/IEEE 29148:2018 on traceability. IEEE Std 830-1998, §4.3: traceable. ISO/IEC/IEEE 15288:2023 on allocating requirements to the parts of a system. |
| Quality attributes | Each of the nine product quality characteristics is covered by a measurable requirement, or left out for a stated reason. | ISO/IEC 25010:2023, the product quality model. |
| Interfaces | Contracts between subsystems give a type, a payload down to its fields, errors and timing. External systems are named. | ISO/IEC/IEEE 29148:2018 on interface requirements. ISO/IEC/IEEE 15288:2023. IEEE Std 830-1998 on external interfaces. |
Priorities weigh every check: a Must item counts three times as much as a Could, and a Won't item is left out. The levels are MoSCoW's, from the DSDM method. An import from OpenSpec or Spec Kit reads each requirement's level from its RFC 2119 keyword: MUST and SHALL as Must, SHOULD as Should, MAY as Could.
Placeholders such as TBD count against the item they sit in: an incomplete requirement, one of the quality indicators of NASA's Automated Requirements Measurement tool (Wilson et al., 1997).
Where the score departs from the standards, it says so:
- Not everything the standards describe is scored. The product context of a specification, a glossary, and the category and risk attributes are left out; What it does not score says why. ISO/IEC/IEEE 29148 offers attributes to choose from rather than requiring each of every requirement.
- Only facts cap the score. A model's finding, such as a conflict between two Must requirements, lowers its area, never the whole score.
- Model checks are repeatable. One pinned model judges them, with versioned prompts, and each verdict is kept with the text it judged, so the same text keeps the same verdict.
- The weights are expert starting values. They have not yet been fitted to outcomes, such as how often a coding agent has to ask a question, or how much of a story is reworked.
References
- ISO/IEC/IEEE 29148:2018. Systems and software engineering: Life cycle processes, Requirements engineering.
- ISO/IEC 25010:2023. Systems and software engineering: Systems and software Quality Requirements and Evaluation (SQuaRE), Product quality model.
- ISO/IEC/IEEE 15288:2023. Systems and software engineering: System life cycle processes.
- IEEE Std 830-1998. IEEE Recommended Practice for Software Requirements Specifications. Superseded by ISO/IEC/IEEE 29148, and still widely cited.
- INCOSE Requirements Working Group (2023). Guide to Writing Requirements, version 4.
- Lucassen, G., Dalpiaz, F., van der Werf, J. M. E. M. and Brinkkemper, S. (2016). Improving agile requirements: the Quality User Story framework and tool. Requirements Engineering 21(3), 383–403.
- Wake, B. (2003). INVEST in good stories, and SMART tasks. xp123.com.
- Zowghi, D. and Gervasi, V. (2003). On the interplay between consistency, completeness, and correctness in requirements evolution. Information and Software Technology 45(14), 993–1009.
- Femmer, H., Méndez Fernández, D., Wagner, S. and Eder, S. (2017). Rapid quality assurance with Requirements Smells. Journal of Systems and Software 123, 190–213.
- Wilson, W. M., Rosenberg, L. H. and Hyatt, L. E. (1997). Automated analysis of requirement specifications. Proceedings of the 19th International Conference on Software Engineering (ICSE '97), 161–171.
- Bradner, S. (1997). Key words for use in RFCs to indicate requirement levels. RFC 2119, IETF.
- DSDM Consortium. The DSDM Agile Project Framework: MoSCoW prioritisation.