How recommendations work
Every scored story comes with an ordered list of recommendations: concrete, plain-English changes that would raise the story's health score and remove the biggest sources of sprint risk.
What a recommendation is
Plain language first
Every recommendation is written as guidance a product owner or engineer can act on directly. No INVEST codes in the recommendation text itself.
Ordered by impact
Recommendations are returned in order of the improvement they would make to the overall score. Work through them top to bottom.
Tied to a dimension
Each recommendation is anchored to the INVEST dimension that produced it so you can trace why it was suggested.
How they are generated
When a ticket is submitted for evaluation, the Vindex scoring engine sends the story's summary, description, and acceptance criteria to the underlying model along with the INVEST dimension rubrics.
The model returns the six per-dimension scores, the context it relied on for each one, and a set of improvement suggestions. The engine ranks those suggestions by the expected lift to the overall score and stores the top handful as top_recommendations.
Recommendations reflect the story text at the moment of scoring. Edit the ticket and re-score to get a fresh list.
Examples
The story
“Users should be able to export their data. The export should work well.”
Recommendation
Add acceptance criteria that describe the observable result — for example: “Given a signed-in user, when they click Export, a CSV file downloads containing all their data rows with headers.”
The story
“Redesign the settings area, including profile, notifications, billing, and integrations.”
Recommendation
Split into four stories, one per settings surface. Each one is independently demo-able and fits in a single sprint.
The story
“Migrate the feature flag service to the new platform.”
Recommendation
State the user- or business-facing outcome. Who benefits, and how? If the benefit is only internal, consider framing the parent goal (for example, faster release cycles) in the story.
Using them in refinement
- Open any story below the quality gate during refinement.
- Work through the top recommendations in order. Paste each one directly into the refinement discussion if that's useful.
- Edit the ticket summary, description, or acceptance criteria based on the feedback.
- Hit Re-score (or wait for the next automatic evaluation). The score and recommendations will update.
- Repeat until the overall score clears the quality gate — or mark the story as intentionally in-progress if you need more conversation before it is ready.