Quality review
Heimdall reads a story, a requirement or a business rule against INVEST, clear wording, testability, the project's business rules and its siblings, scores it out of 100 and lists what to fix; nothing changes until you do.
By the end of this page you will have asked Heimdall to review a story, read its score and the findings behind it, taken one finding to the Heimdall panel to fix it, reviewed the story again and watched the badge on the backlog follow; you will also know exactly what Heimdall checks for each kind of record, how the score is built, what a review costs and what it announces.
A quality review is Heimdall reading one planning record the way the people after you will: a developer who has to build it, a tester who has to prove it, a client who has to sign it off. It reads the record, the rows that belong to it, what it is linked to, the project's business rules and the titles of its siblings, and answers with findings, each a plain sentence on what is wrong or missing, quoting the words concerned, with a suggestion in the record's own words. The score out of 100 is arithmetic over the findings, so a 71 always means the same thing, and the band turns it into one word for a badge: ready, needs work or not ready.
Reviews live in the Quality panel of the detail flyout on three pages: the Backlog for stories, tasks, bugs, spikes and improvements, the Requirements page for functional and non-functional requirements, and the Business rules page. Nothing on the record changes when Heimdall reviews it: the findings are yours to act on, and the record's history stays the record of what people and accepted drafts wrote.
Before you begin
| To | You need |
|---|---|
| Read a record's reviews | A staff account that can open the record. A client guest never sees the panel. |
| Ask Heimdall for a review | ai:use on the team and the project's AI assists switch on under Settings → AI; a client guest never asks. |
| Take a finding to the Heimdall panel | The same ai:use, since the panel is Heimdall's. |
| Have room in the team's monthly AI budget | A review is one metered call; when the month's cap is reached Heimdall refuses until an admin raises it. |
The record must be saved first: Heimdall reviews what is on the record, not what is in an open editor, and the review remembers which version it read.
Reviewing a record
Open the record and find the Quality panel
Open the story, requirement or rule from its list; the flyout shows the record, then its versions, then the Quality panel, above the links. A record never reviewed shows one sentence on what Heimdall looks for and a Review now button.
Press Review now
Heimdall reads the record and what the project holds around it, which takes a few seconds; the button says Heimdall is reading… until the answer lands. A toast tells you the score and how many findings there are, the panel fills, and the record's row in the list gains a small score badge.
Read the score and the summary
The badge at the top of the panel shows the score out of 100 and its band, who asked and when, and the version of the record that was read. Under it, two or three sentences from Heimdall on the record as a whole: what is sound and what the findings add up to. A record with nothing to fix scores 100 and says so.
Read the findings, most serious first
Each finding is one card: a severity badge, the kind of problem (hover it for one line on what the kind means), the field concerned when there is one, the finding itself quoting the words Heimdall objects to, and Try: followed by a suggestion in the record's own words. Findings are ordered by severity, high first.
Take a finding to Heimdall
Ask Heimdall on a finding opens the Heimdall panel with the finding already written into the composer, naming the record and quoting the message and the suggestion. Nothing is sent until you press Enter, so add what Heimdall could not know, then let it read the record with its tools and propose the rewrite; you make the change in the editor yourself.
Fix the record and review again
Edit the record as usual and save. The panel now shows Record changed since beside the score, because the review read an earlier version. Review again asks Heimdall for a fresh reading; the earlier reviews stay on the record, newest first, so the history of a story's quality reads in order over the API.
Every review is one call to the model, filed in the team's AI ledger under Quality reviews and counted against the month's budget on Settings → AI. Review a record when it changed or was never reviewed, not after every keystroke; the panel always shows the latest review, so there is nothing to gain from asking twice.
How the score is built
Heimdall never names a number. It names findings and grades each one, and the score is 100 less the penalties of the findings, never below 0:
| Severity | Meaning | Penalty |
|---|---|---|
| High | A developer or a tester would be blocked or misled by the record. | 25 |
| Medium | The record is usable but would be argued over. | 10 |
| Low | Polish: a word, a missing example, a sharper title. | 4 |
The band reads the score for you:
| Band | Score | Read it as |
|---|---|---|
| Ready | 80 to 100 | Fit for the people after you; the findings, if any, are polish. |
| Needs work | 50 to 79 | Usable with questions; fix the medium and high findings before it is picked up. |
| Not ready | 0 to 49 | Something would block a developer or a tester; rewrite before anyone estimates it. |
Two high findings alone take a record to 50, so a story missing its criteria and hiding three stories in one title is not ready whatever else it does well. That is the point: the number reflects what would hurt downstream, not how long the record is.
What Heimdall checks
The kinds of finding
| Finding | Code | Meaning |
|---|---|---|
| Not independent | independent | The story only makes sense together with another story. |
| Over-specified | negotiable | The story dictates the implementation instead of the outcome. |
| Value unclear | valuable | The story does not say what a persona or the business gets from it. |
| Hard to estimate | estimable | The story is too vague to size. |
| Too large | small | The story is an epic in disguise and should be split. |
| Not testable | testable | No criterion of the story can pass or fail. |
| Ambiguous wording | ambiguous | Words such as fast, easy, appropriate or some leave the meaning open. |
| Criteria missing | missing_criteria | The story has no acceptance criteria, or they restate the title. |
| Cannot be verified | untestable | A statement or criterion cannot be verified. |
| No measure | missing_measure | A non-functional requirement has no measurable target. |
| No rationale | missing_rationale | Nothing says why the requirement exists. |
| No worked example | missing_examples | The rule has no worked example. |
| Incomplete | incomplete | A condition, action, expected result or outcome is missing. |
| Conflicts with a rule | rule_conflict | The record contradicts a business rule of the project, named. |
| Possible duplicate | duplicate | Another record of the project may already say the same, named. |
| Off the house stack | stack_drift | The record assumes a technology the house does not build with. |
| Other | other | Something else worth fixing. |
Convening the council
Beside Review now, people who may use Heimdall see Convene the council: a menu that summons every voice the project seats on a requirement review at once (Every seated voice) or one of them alone (Ask Thor, Ask Loki, and so on), for the question you have. Each voice reads the record through its own lens, Heimdall writes the verdict, and the Heimdall panel opens on its Council tab to show the sitting as it fills in; a line under the review names the newest sitting's state with Open the sitting. One sitting per record at a time; the menu returns when it is done. Who sits, what each voice reads, what accepting a finding writes and what a sitting costs is on the council page.
The badge on the list
Once a record was reviewed, its row on the Backlog, the Requirements page and the Business rules page shows a small badge beside the reference with the latest score, coloured by its band; hover it for the band's name. The badge is the latest review whatever the record did since, so a story rewritten after a poor review keeps its old score until someone reviews it again. The three pages refresh the badge the moment a review finishes in the flyout.
What happens next
- The review is kept on the record with its findings, the version it read, who asked and the ledger row that filed the call; earlier reviews are never overwritten.
- The call is filed in the team's AI ledger under Quality reviews and moves the month's budget; crossing the warning line or the cap tells the team's admins the way every other call does.
work_item.quality_reviewed,requirement.quality_reviewedorbusiness_rule.quality_reviewedgoes out with the score, the number of findings and the version read, so a dashboard can follow a project's quality without reading the findings.- The record itself is untouched: no version is written, no status moves, no field changes.
- When Heimdall cannot reach its model, the panel says so, nothing is filed and nothing is kept; try again in a moment.
From the API and MCP
Work items API
List a work item's reviews, or ask for one, under the item.
Requirements API
The same two verbs under each requirement.
Business rules API
The same two verbs under each rule.
review_quality
An agent asks Heimdall for a review of a record it is about to implement.
list_quality_reviews
An agent reads the latest findings before it starts, free of charge.
An agent reads a record's reviews with activity:read and asks for one with ai:use; the reads
need the record's own view ability over REST. A client guest's token is refused both ways.
Permissions
| Action | Permission |
|---|---|
| See the Quality panel | A staff account that can open the record; never a client guest |
| Ask for a review | ai:use, with the project's AI assists on |
| Read reviews over REST | work-item:view, requirement:view or business-rule:view, staff only |
| Ask for a review over REST | ai:use |
| Read reviews from an agent | activity:read |
| Ask for a review from an agent | ai:use |
Frequently asked
Does a review change my record? No. It is kept beside the record and shown in the panel; you decide what to do with each finding, and the record's history records only what you and accepted drafts wrote.
Why did the score not change after I fixed a finding? The panel shows the latest review, which read the version before your edit; it says Record changed since to tell you. Press Review again for a fresh reading.
Can I review a record that is approved or baselined? Yes. A review reads; it never writes, so the approval rules do not apply. The findings are still useful for the change request that follows.
Why is the panel missing for my client? A client guest never sees reviews: findings are the team's working notes and often quote the gaps the client has not seen yet.
How much does a review cost? One model call, filed under Quality reviews on Settings → AI with the tokens it used. A long story with many criteria and a project with many rules costs more than a short one, because Heimdall reads them all.
Can Heimdall review on every save? Not today: a review is asked for, so the budget is spent on purpose. The council that lands with the brief import will review a record when it is submitted for approval.
Related
- Backlog — the stories, tasks and bugs the panel sits on
- Acceptance criteria — the rows a story is judged by
- Functional requirements and Non-functional requirements — statements, measures and verification methods
- Business rules — the rules a conflict is checked against
- Revisions and versions — the version a review read, and why the record's history stays untouched
- Inline assists — rewrite a field once you know what is wrong with it
- Heimdall and quality — how the reviewer thinks and what it costs
- Settings → AI — the budget the reviews draw on
- Status reference — bands and severities
How is this guide?
Last updated on
Business Rules
The Business Rules page of a project: the decisions of the business the system must honour, each with its kind, statement, condition and action, exceptions, worked examples, authority, priority, dates in force, status and owner, its review lifecycle and its versions.
Brief import
Paste a brief, let Heimdall draft epics, stories, requirements, rules, terms, personas, risks and decisions from it, and accept, edit, merge or reject each suggestion from a review queue; nothing lands until you say so.