stack-proposal

name

stack-proposal

description

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.
• constraints (optional): budget, downtime tolerance, deadlines, must-keep components.

Procedure

1. Load everything

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:

1. Additive before subtractive. Add the new thing, cut over, then remove the old one. Never in one step.
2. Reversible before irreversible. Anything touching data goes late and carries a rollback plan.
3. Unblock first. A runtime upgrade that unblocks four other items goes before all four.
4. 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.