How do I read a Vindex result in my assistant?

A Vindex result in your assistant leads with the finding, then the overall percentage and its band, then the six dimensions if you ask. Read the finding first. It is the one change that moves the score most, written so that anyone who has shipped a bad story recognizes it.

The order is deliberate. A percentage on its own invites arguing about the number; a dimension code (“T: 30%”) means nothing to someone who has not memorized INVEST. “Acceptance criteria are missing or untestable” tells you what to do next.

What arrives, and in what order?

1. The finding. The highest-impact recommendation, rephrased as a plain statement about the story.
2. The overall percentage and band. Scores are whole percentages, never a score out of ten. The band is one of Healthy, Needs review, or At risk.
3. The recommendations. Ordered, highest impact first. Two or three is typical; the finding is the first of these.
4. The dimensions, on request. Independent, Negotiable, Valuable, Estimable, Small, Testable, each with a percentage, a sentence of reasoning, and specific suggestions.

Assistants render this differently. Claude and ChatGPT tend to show the finding and band and offer the detail; a coding agent may quote the structured fields. Ask for “the full Vindex result” when you want everything at once.

What does each band suggest?

• Healthy, 80 to 100. The story reads as ready to plan. Recommendations, if any, are refinements rather than gaps.
• Needs review, 60 to 79. Borderline. Usually one or two dimensions are dragging: read those, decide whether the gap is real for your team, and either fix it or accept it knowingly.
• At risk, 0 to 59. As written, the story is likely to turn into rework or a defect. The finding names why.

The band is a suggestion. Nothing in Vindex blocks a story or changes it. Teams that want a hard rule write one themselves, for example in a coding agent’s standing instructions; the rule is theirs to set and to change.

How do I read a dimension?

Each dimension has three parts: the percentage, one sentence of reasoning that says what Vindex saw, and suggestions that say what would change it. Read the reasoning before the number. A Testable score of 60 with the reasoning “criteria are present but lack timing expectations and edge cases” is a different problem from a Testable score of 30 with “there are no acceptance criteria,” and the fix is different too.

If a dimension name means nothing yet, ask the assistant to explain it. It calls explain_invest, which returns the definition, what Vindex looks for, and the common failure patterns, without using any of your allowance.

What happens when I fix the story and ask again?

You get a fresh evaluation, and it is free. A story counts against the company’s monthly allowance once; every later score of the same story costs nothing, in any month. Give the assistant the tracker key when the story has one (the Jira key, the Azure DevOps work item id, the Asana task), so the assistant and the tracker plugin agree on which story they are scoring.

How do I check the team’s allowance?

Ask the assistant to check Vindex usage. It calls get_usage and reports the company, the plan, stories counted this month, the allowance, and what remains. The arithmetic is the same the Vindex Portal shows, so the two never disagree. Free plans cover up to 10 stories a month; re-scores never count.

What if the assistant paraphrases the numbers?

Assistants sometimes summarize a result in their own words and round or misremember a percentage. The percentages are Vindex’s; the prose around them is the assistant’s. If a number looks off, ask for the result as Vindex returned it. And if what comes back is a single sentence with no numbers at all, that is a Vindex error message (a timeout, a busy company, or an exhausted allowance); try again in a moment, or check usage.