Qstack Plan Close

/qstack-plan-close

Turns a finished piece of work into compounding knowledge.

The plan is not the lesson. The lesson is the delta between the plan and reality: what diverged, what surprised you, what cost hours that nothing predicted. This skill captures that delta and writes it where the next plan in this area will read it.

The convention

qstack/compound_engineering/plans/<feature-slug>/
├── plan.html                  # BEFORE: what we predicted. Frozen once work starts.
├── board-events.js                # DURING: append-only card events, written by agents.
├── execution.md               # DURING: decisions, deviations, validation, and reviews.
└── outcome.md                 # AFTER: this skill writes it.

If the repo has qstack/compound_engineering/README.md, read it first: it may extend or override what follows. Also support the legacy compound-engineering/plans/<feature-slug>/ layout and its README. Prefer the QStack layout when both contain the requested feature. If neither plan root exists, offer to create the QStack layout before proceeding.

Hard rules

• Never edit plan.html or legacy plan.md. The plan is frozen once work starts; divergence is recorded in outcome.md, not by rewriting history.
• Never commit. Write files and stop. The user commits.
• Do not implement anything. This skill only writes documentation.

Steps

1. Identify the plan folder

ls qstack/compound_engineering/plans/
ls compound-engineering/plans/  # legacy, when present

If the user named a feature, use it. If not, infer from the current branch and recent commits, then confirm with the user before writing.

2. Establish ground truth

Do not rely on the plan's claims. Gather what actually happened:

git log --oneline --format='%h %ad %s' --date=short -20 -- <paths the plan touched>
git log --all --oneline --diff-filter=A -- '<resolved-plan-folder>/*'

Then verify the shipped surface exists: ls the scripts, grep for the key symbols the plan promised. A plan that says it shipped foo_bar() and a tree with no foo_bar() is the single most valuable finding this skill can produce.

Read board-events.js when the plan has one. Run node --check, then fold the qstackBoardEvent({...}); calls after the required format header in file order; later events win. Stop on broken JavaScript, and take every count from that fold rather than from a summary written by hand. A plan with no board leaves only the execution record; say which one you used.

When only the retired board.jsonl exists, fold its raw JSON lines under the same state rules and name the legacy source in outcome.md. If both board files exist, stop because the execution record has two sources of truth.

Check whether the plan's artifacts were ever committed at all. Work done in a gitignored directory leaves no recoverable design record: worth stating plainly in the outcome when it happened.

3. Extract the delta

Read plan.html in either plan-root layout, falling back to legacy plan.md, especially any "Locked decisions" and "Open questions" sections. Read every execution record that exists beside it: prefer execution.md, but also read implementation-notes.md because it may contain earlier history. State legacy sources in the outcome. Compare all of them against the tree. Produce:

• Where it diverged: decisions the implementation reversed or refined, and why. Include names that changed (a plan calling a file CONTRACT.json when the tree has .fs-contract.json will mislead every future reader).
• What surprised us: anything that cost real time and no plan revision predicted. This is the highest-value section; mine the notes' validation log and audit findings for it.
• Contradictions: where the plan and CLAUDE.md now disagree. Flag as unverified rather than guessing which is right.

If both execution-record files are missing, or the available records are thin, say so plainly in outcome.md rather than inventing detail. Note that the execution record was not kept.

4. Check the board is closed

Every card in the fold must be done or split. If any card is backlog, claimed, in-progress, review, or blocked, do not write outcome.md. Name the open cards with their status, owner, and points, and stop. A plan with work still on the board has not finished, whatever the tree looks like.

The board itself must also be stood down. A coordinator event with no later stood-down from the same actor means one actor still holds the whole board, and its backlog cards can be claimed while you are writing the outcome. Name that actor and the claim's ts, and stop. Only a human settles it. This skill never decides that a holder is gone.

The user can override by saying so. Record the override in outcome.md along with the cards that were open and any coordinator still holding the board when it was given. A plan with neither board format skips this step.

5. Write outcome.md

status:  proposed | approved | in-progress | shipped | abandoned
date:    YYYY-MM-DD
commits: <sha + subject, one per line>

Then: What shipped (table of real paths), Where it diverged from the plan, What surprised us, Open follow-ups (cross-check TODO.md).

When the plan has a board, add one Board line under the front matter: points closed of points planned, how many cards split, and every card that ever entered blocked with what unblocked it. Scan the raw lines for the blocked ones, not the fold, which only holds the final status. Cards that spent time blocked are the cheapest honest signal of what actually cost time: a card stuck for two days on a question nobody answered cost two days, whatever its points say.

For status: proposed, open the file with a loud no-implementation-authority block. An unapproved design must never read as a specification.

6. Where a lesson goes

The lesson stays in outcome.md, where it is read by whoever plans the next thing in this area. That is what /qstack-plan-prior-art is for, and it reads the whole plan folder before a new plan is drafted.

A rule strong enough to belong everywhere is not a plan lesson at all. It is a guardrail. Hand it to /qstack-encode-lessons-in-structure, which turns it into a type, schema, lint, check, or script that enforces itself.

Neither path grows an always-loaded instruction file. This skill no longer edits CLAUDE.md or AGENTS.md.

7. Update the index

Add or update the row in the resolved plan root's README → "Current plans".

8. Report

Summarize: status set, what diverged, what the board closed, what follow-ups remain open. State clearly that nothing was committed.

The index, when the folder grows

Once the plan folder holds a few dozen plans, opening every folder to find prior art costs more than it returns. At that point this skill should append one line per closed plan to plans/INDEX.md: slug, start and close dates, the outcome in one sentence, and the files touched: so /qstack-plan-prior-art reads the index for closed plans and opens folders only for the live ones.

It is deliberately not built yet. Below about 30 plans, reading the folders is cheaper than keeping a second record honest, and an index that drifts from the folders is worse than no index.