stack-diff

name

stack-diff

description

Compare the current stack against the last recorded evaluation in the same repository — components added, removed or upgraded, findings closed, ignored or gone chronic, decisions that have expired, and drift from the last accepted proposal. Use when the user says "what changed since last time", "did we act on the last review", "has the stack drifted", "compare to the last run", or on any re-run of stack-inventory in a repo that already has docs/stack/stack.json. This is what makes repeated evaluation worth more than a one-off.

stack-diff

The second run is where this plugin earns its keep. A one-off review is a snapshot; a series shows whether anything actually happened.

Inputs

• path (optional): repo root. Defaults to cwd.
• since (optional): a specific prior run date. Defaults to the most recent entry in history[].

Procedure

1. Load both states

Read docs/stack/stack.json. It carries the current components plus history[] and findings with their first_seen dates and statuses.

If history[] is empty, this is the first run — say so plainly and stop. There is nothing to diff and inventing a comparison against an imagined baseline is worse than saying "baseline recorded, run again after the next round of work".

For the prior detail, read docs/stack/reports/<since>-*.md and any docs/stack/proposal-<since>.md.

If stack.json predates the current HEAD by a long way, re-run stack-inventory first so the "current" side of the diff is actually current.

2. Diff the components

Four buckets:

• Added — new slots filled, or new components in an existing slot. Was this in a proposal, or did it arrive unplanned? Unplanned additions are worth naming, not as a criticism but because a component nobody decided to add is a component nobody owns.
• Removed — gone since the last run. Confirm it was intentional; a component that vanished from a manifest without a corresponding finding is worth a question.
• Upgraded / downgraded — version moves. Note whether each closed a currency or EOL finding.
• Unchanged — count them; do not list them.

3. Diff the findings

This is the substance of the diff:

Transition	Meaning	How to report it
open → done	Fixed	Name it. Closed findings are the return on running this.
open → rejected	Decided against	Confirm it stays rejected; do not re-raise.
open → open, first_seen old	Chronic	State how long it has been open.
New finding	Appeared since last run	Did a change cause it?
Was open, now absent	Resolved incidentally, or the evidence moved	Verify which.

Findings open across three or more runs are the ones to lead with. Something open for six months is either genuinely blocked, wrongly scoped, or not actually a problem — say which you think it is and recommend re-scoping or rejecting it rather than carrying it silently into a fourth run.

4. Check proposal follow-through

If a proposal-<since>.md exists, walk its work items against reality:

• Landed as specified
• Landed differently — note the divergence without judgement; the executing engineer may have had better information
• Not started
• Superseded by something else that happened

Deferred items get their promotion trigger re-checked: has the load threshold been crossed, has the support end date arrived, was the feature that would need it built?

5. Check decision expiry

Walk every intentionally-absent slot and every rejected finding and ask whether the stated reason still holds. Reasons expire quietly:

• "No production data yet" against a repo that now has a production deploy target
• "Single user" against a repo that has grown an auth layer
• "No measured load" against a project that has since added caching elsewhere
• A rejection premised on a constraint that has lifted

Where a reason has expired, reopen the finding with the expiry noted. Where it holds, leave it and say nothing — silence on settled questions is a feature.

6. Note archetype drift

If the archetype classification changed since the last run, that is the headline. A static site that grew a database, or a library that grew a server, is now measured against a different checklist and will have gaps that did not exist before because the expectations moved.

7. Record

Append to history[]. Write docs/stack/reports/<date>-diff.md.

Do not rewrite prior reports. The trail is the point; an evaluation series that gets tidied retroactively cannot show what was believed when.

8. Report

In this order: what got fixed, what is chronic, what appeared, what drifted, what decisions expired. Lead with the fixed items — a diff that opens with problems reads as though nothing has improved even when things have.

Close with whether the stack moved toward or away from the last accepted target state.

Guardrails

• Do not fabricate a baseline. No history means no diff.
• Preserve first_seen on carried-forward findings. Resetting it erases the chronic signal that makes this skill useful.
• Do not re-raise rejected findings unless the reason has demonstrably expired, and say which reason and why when you do.