| 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.
