Staleness and reconciliation

When you change a feature, VibeMap tells you which stories and criteria underneath it are now out of date — and offers to rewrite them, with your approval on every line. · Recommended

Read this if your spec has started to move: you've reworded a feature, sharpened a user story, or changed your mind about what something does. The work you generated from those parents doesn't update itself, and it doesn't announce that it's out of date — which is how a spec quietly becomes fiction. Staleness makes it announce itself.

If you're looking for the gaps that stop a build rather than the drift inside one, see Prepare for Dev instead.

What makes something stale

Your spec is a chain: a feature produces user stories, and a story produces acceptance criteria. Each child was written from the parent as it read at that moment. VibeMap remembers that moment — every change to your project is recorded (version control), so it can compare when a child was written against when its parent last changed.

A child is stale when both are true:

1. The parent changed after the child was written. Not merely edited around the same time — genuinely later in your project's history.
2. The change was material. VibeMap only counts edits to the fields a child was actually derived from: a feature's name, description, category, kind, or business value; a story's title, description, its I want to / so that wording, or its user role. Flipping a status, priority, or effort estimate changes nothing downstream, so it never marks anything stale.

Two consequences worth knowing:

• An edit you undid doesn't count. If a field changed and then changed back, it nets to zero — the child never really saw a different parent.
• Staleness needs history. A project with no recorded change history has nothing to compare, so nothing is ever marked stale. Version control starts recording the first time the conversational agent makes a change on a project — see When history starts recording.

⚠️ Watch out: "Stale" means worth a second look, not wrong. A feature rename often leaves its stories perfectly valid. VibeMap flags the candidates; you decide.

The Stale badge

On a feature's detail page, a small amber Stale pill appears on any user story or acceptance criterion whose parent has moved on — on the story card next to its AC count, and on the criterion row itself.

Click it and a Changed upstream popover explains itself: one sentence naming what changed ("Story X may be stale — feature Y changed after it was written (description)"), then each changed field with the old value struck through above the new one. It's the smallest possible answer to "why is this flagged?" — no navigation, no diff-hunting.

The badge only informs. Rewriting happens in the reconcile flow below.

Findings, and what they block

A stale item is one kind of finding — VibeMap's single word for anything it noticed about your spec. Coverage gaps, referential-integrity errors, traceability gaps, staleness, and code drift are all computed into one list, so the same item never shows up three times under three different labels.

Findings are listed in the Overview panel of the Blueprint Preview Map, grouped by kind — staleness appears as Stories with upstream changes and Criteria with upstream changes. They also feed the Spec health score in the Readiness panel on Prepare for Dev, where staleness deducts a small, capped amount.

Staleness never blocks your build. It's a reconcile prompt, not a defect: a stale story is still a story, and your agent can build from it. The findings that do hold the ready-to-build gate — missing stories, missing criteria, broken references, unbound UI states — are listed in Blocking vs. non-blocking findings.

Reconciling: the four steps

Reconciliation is the guided rewrite: VibeMap proposes updated wording for each stale item, and you accept or reject it one item at a time.

Open the Prepare for Dev page, find a stale group in the map's Overview panel, and click Reconcile. The dialog runs in four steps.

1. Preview what changed upstream

Before anything is generated, you see the raw facts: each stale item, the upstream feature or story that changed, and every changed field with its before and after values. Nothing has run yet — this step costs nothing and you can cancel out of it.

Click Propose updates to continue.

2. Analyze

VibeMap sends the upstream change and the current content of each stale item to the model, and asks for proposed rewrites. This is the only generation in the flow.

If everything is already consistent, you'll be told so plainly — "The AI found these items already consistent with the upstream changes — nothing to update" — and there's nothing to approve.

3. Review, item by item

Each proposal is a row with its type (User Story, Criterion), the action it takes, the proposed text, and a confidence label. High-confidence items are pre-ticked; medium and low start unticked, so the ones the model is least sure of require a deliberate yes from you. Select all and Clear are there when you want to move fast in either direction, and any proposal that conflicts with something else in your spec carries an amber conflicts detected warning.

Unticking is not neutral: anything left unticked is explicitly rejected and its item stays exactly as it is.

⚠️ Watch out: Nothing is written to your spec until you apply. Closing the dialog, cancelling, or clicking Dismiss leaves every stale item untouched — Dismiss also throws away the proposals so a later reconcile starts fresh.

4. Apply

Apply N selected writes the approved rewrites and reports back how many landed (and how many failed, if any). Only then does your spec change.

What reconciliation will and won't do

Reconciliation is deliberately narrow. It is not a re-generation, and it can't quietly reshape your project while your attention is on the wording:

Everything it applies goes through version control as a single change, so the whole reconciliation is revertable in one click from the History tab — see Reverting changes. It's also recorded as an amendment in the Requirements panel on your project Overview, titled "Reconcile downstream of: …", which bumps your requirements version.

⚡ Power-user hints

• Reconcile in batches, per parent. Clicking Reconcile on a group sends every stale item in it into one review, so a single feature rewrite becomes one dialog instead of six.
• Read the low-confidence rows properly. Confidence is the model's own assessment. High-confidence rewrites are usually a re-phrasing; low-confidence ones are where it's guessing at your intent — those are the rows worth editing by hand afterwards.
• Fix the parent first, then reconcile once. Reconciling after every small edit generates proposals you'll throw away. Get the feature right, then push the change downstream in one pass.
• A stale badge that won't clear usually means the item genuinely still needs a human rewrite — reconcile proposes updates, but you can always edit the story or criterion directly instead.

↔ The traditional way

Normally, nothing connects a changed requirement to the tickets written from it. A PM sharpens a feature description in a doc, and the twelve stories and forty criteria underneath it stay as they were until someone notices mid-sprint that the ticket and the requirement disagree — usually after the wrong thing has been built. Teams handle it with discipline: a "spec review" meeting, a manual sweep, a stale-ticket bot. VibeMap knows precisely which children came from which parent and when, so it can name the twelve affected items, propose the rewrite, and let you approve it line by line in a couple of minutes.

What's next

• See which findings actually block your build → Prepare for Dev
• Where the findings list lives → The Blueprint Preview Map
• The score these findings feed → The project Overview
• Undo a reconciliation → Reverting changes
• When your code, not your spec, moved on → Drift detection