Turn stack findings into a decided, sequenced revision of the stack plus a self-contained execution brief that an implementing agent can act on without re-running the evaluation. Produces a target-state component table, ordered work items with blast radius and rollback, and explicit non-goals. Use when the user says "propose a revised stack", "what should we change", "give me a migration plan", "hand this to an execution agent", "write up the stack changes". Reads docs/stack/stack.json; run stack-inventory plus at least one of stack-currency, stack-gaps, stack-fitness first.
Turn stack findings into a decided, sequenced revision of the stack plus a self-contained execution brief that an implementing agent can act on without re-running the evaluation. Produces a target-state component table, ordered work items with blast radius and rollback, and explicit non-goals. Use when the user says "propose a revised stack", "what should we change", "give me a migration plan", "hand this to an execution agent", "write up the stack changes". Reads docs/stack/stack.json; run stack-inventory plus at least one of stack-currency, stack-gaps, stack-fitness first.
stack-proposal
Findings become a decision, a sequence, and a brief someone else can execute.
The output is written for an agent or engineer who was not in this session and will not re-read
the evaluation. Everything needed to act must be in the brief.
Inputs
path (optional): repo root. Defaults to cwd.
appetite (optional): how much change is on the table — minimal, moderate, overhaul.
Ask if not given. It changes the answer more than any technical input.
Read docs/stack/stack.json and any docs/stack/reports/<date>-*.md from this run's date.
If only the inventory exists, say what is missing and offer to run the analysis skills first. A
proposal built on an inventory alone is a list of version bumps.
2. Get appetite and constraints on the record
Ask, in one message, if not already known:
How much change is acceptable right now — a few safe fixes, a planned round of work, or a real
overhaul?
What must not change? Existing platform commitments, contracts, a component the user likes.
What is the tolerance for downtime and for regression risk?
Is there a budget direction — reduce spend, hold, or spend to remove toil?
Appetite is what separates a useful proposal from an ignored one. minimal means the proposal
should contain three items, not fifteen.
3. Decide, do not enumerate
Every open finding gets a disposition:
Do now — the fix is clear, the payoff is clear, it fits the appetite.
Do later — real, but not now. Give the trigger that should promote it: a load threshold, a
support end date, a feature that would need it.
Won't do — with the reason. Write these back to stack.json as rejected so no future run
re-raises them. This is the field that keeps re-runs quiet.
Do not present a menu of options with trade-offs and leave the choice open. Recommend one thing.
Where a genuine fork exists, state the recommendation and the one condition under which the other
choice would be right.
4. Build the target state
A table of the stack as it should be, not a diff:
Slot
Current
Target
Change
runtime
Node 18 (EOL 2025-04-30)
Node 22 LTS
upgrade
cache
—
HTTP Cache-Control + Cloudflare edge
add
queue
Kafka
Postgres job table
replace
search
Elasticsearch
—
remove
database-primary
Postgres 16
Postgres 16
keep
Include the unchanged rows. A target state that only lists changes hides how much of the stack is
staying put, which is usually most of it and is reassuring to see.
5. Sequence the work
Order by dependency and risk, not by severity. The rules that matter:
Additive before subtractive. Add the new thing, cut over, then remove the old one. Never in
one step.
Reversible before irreversible. Anything touching data goes late and carries a rollback plan.
Unblock first. A runtime upgrade that unblocks four other items goes before all four.
Independent items in parallel — mark which items have no ordering constraint, so the work
can be split.
Each item gets: what changes, why, files and services touched, effort, blast radius, how to verify
it worked, and how to undo it. An item without a verification step is not ready to hand off.
6. State the non-goals
Explicitly list what this proposal does not touch, and why. Without this, an execution agent
reads a stack proposal as licence to modernize everything it sees.
Include here anything deliberately kept: "Postgres stays on 16 — supported until 2028-11-09,
no reason to move."
7. Write the proposal
docs/stack/proposal-<date>.md:
# Stack revision proposal — 2026-07-31**Archetype:** api-service · **Appetite:** moderate · **Based on:** stack.json run 2026-07-31 (a1b2c3d)
## Summary
Three sentences. What is wrong, what changes, what it buys.
## Target state
[table from step 4]
## Work items### 1. Upgrade Node 18 → 22 LTS-**Why:** Node 18 reached EOL 2025-04-30; no security patches.
-**Blocks:** items 3 and 4.
-**Touches:** .nvmrc, Dockerfile, .github/workflows/ci.yml
-**Effort:** S · **Blast radius:** contained
-**Verify:** CI green on 22; container starts; `/health` returns 200.
-**Rollback:** revert the pin; no data or state involved.
### 2. …## Deferred
| Finding | Why not now | Promote when |
|---|---|---|
## Not doing
| Finding | Reason |
|---|---|
## Non-goals
This proposal does not touch the frontend framework, the database engine, or the deploy platform.
8. Write the execution brief
docs/stack/execution-brief-<date>.md — the handoff artefact. Self-contained: an agent given only
this file and repo access must be able to work from it.
# Execution brief — stack revision 2026-07-31
You are implementing an approved stack revision. The evaluation is done; do not re-evaluate.
## Scope
Work items 1–4 below, in order. Items 3 and 4 are independent of each other.
## Rules- One work item per commit. Do not combine.
- Do not modify application logic beyond what an item requires.
- Do not upgrade anything not listed here, including transitive pins, unless an item requires it.
- If an item's verification step fails, stop and report. Do not improvise an alternative.
- After each item, update its status in docs/stack/stack.json.
- Documentation for a change ships in the same commit as the change.
## Work items
[full items, copied — not referenced]
## Out of scope
[non-goals, copied]
## Definition of done
All in-scope items landed and verified; stack.json findings marked done; docs/stack/stack.md
regenerated via the stack-inventory skill.
Copy the items into the brief rather than pointing back at the proposal. A brief that requires
reading two other files to act on is the failure mode this artefact exists to prevent.
9. Update the record
Set each finding's status in stack.json to accepted, rejected, or leave open for
deferred items with the promotion trigger recorded in detail.
10. Report
State the appetite you worked to, the number of items in and out, the first thing to do, and where
the two files are. Ask whether to hand the brief to an execution agent now.
Guardrails
The brief authorises exactly what it lists. Any expansion of scope needs the user, not the
executing agent.
No item without a verification step and a rollback path.
Do not propose a big-bang replacement of several components at once. If the target state needs
that, the sequence is wrong — decompose it.
Do not execute the proposal in this skill. Writing and doing stay separate so the user gets a
decision point.
