consolidate-feature

name	consolidate-feature
description	Final stage of the LAD feature workflow, run after a feature is merged. Condenses the working plan and context files into a durable record — appended to the project's existing ADR where one exists, or a new decision record where none does — harvests any new guardrails, and prunes the working files. Use after merging a feature, or when asked to write up what was done and why.
argument-hint	["feature slug"]

Consolidate feature

Run this after the feature is merged, not before.

Working files (<docs>/<slug>/plan.md, context.md, sub-plans) are scaffolding: detailed, quickly stale, and worth little once the work is done. What stays valuable is much smaller — the decisions and the reasons behind them. This stage keeps that and discards the rest.

This is what allows STATUS.md to remain a short statement of the current state rather than accumulating history: superseded detail is retained here instead of being either lost or left to clutter the status file.

1. Gather what actually happened

Do not write this from the plan alone — the plan says what was intended.

• git log --oneline <base>..HEAD and git diff --stat <base>..HEAD for the real shape of the work
• <docs>/<slug>/plan.md — including tasks that were dropped or added mid-flight
• <docs>/<slug>/context.md — particularly the deviations recorded during implementation
• Review comments, if the feature went through a PR

Where intent and outcome differ, the outcome is the record. Note the difference; it is often the most useful line in the document.

2. Find where decisions already live

Do not create a second home for decision rationale. Many projects already have one, and adding a parallel tree beside it means future sessions read whichever they happen to find. Check, in order:

ls .codebase-memory/adr.md ADR.md ARCHITECTURE_DECISIONS.md 2>/dev/null
ls -d docs/adr doc/adr docs/decisions 2>/dev/null

Three cases, and they are handled differently:

Found	Do
A single ADR file (e.g. .codebase-memory/adr.md)	Append a section, in that file's existing format
A directory of numbered records (doc/adr/0004-*.md)	Add the next numbered file, following the local naming and template
Nothing	Create <docs>/decisions/<slug>.md and its index, as in step 3b

Read what is already there before writing. Match its structure and heading style rather than imposing LAD's — a record nobody can scan alongside its neighbours is worth less than a slightly imperfect one that reads consistently.

If codebase-memory-mcp is available and the project uses .codebase-memory/adr.md, prefer manage_adr over editing the file directly, and call it with mode: get first to see the existing structure. The file is tracked in git either way, so a direct edit is not wrong — it just risks diverging from whatever shape the tool maintains.

3a. When an ADR exists

An ADR is organised by decision, not by feature. This matters: some features produce no architecturally significant decision at all, and forcing an entry for every one is how an ADR turns into a changelog nobody reads.

Record only what is durable and would not be obvious to someone reading the code later:

• The choices and why — including the constraint or trade-off that drove each
• Alternatives rejected, and what would make them right in future
• Limitations and open issues the feature introduces or leaves behind

Deliberately skip the transient parts. "What was built" is recoverable from the code and the graph; "deviations from plan" stops mattering once the plan is gone. If nothing survives that filter, say so and add nothing — that is a correct outcome, not a failure.

3b. When there is no ADR

Write <docs>/decisions/<slug>.md. Aim for one page. If it runs much longer, it is holding detail that belongs in the code.

# <slug>

_Merged YYYY-MM-DD · <commit range or PR number>_

## What was built
<two or three sentences, plus the entry points a reader should open first — path:line>

## Choices made, and why
- **<decision>** — <why this and not the obvious alternative>

## Rejected alternatives
- **<option>** — <why not; what would make it right later>

## Deviations from plan
<what changed       ; ""    >

The Rejected alternatives section carries most of the long-term value. A future session that cannot see what was already ruled out will propose it again, confidently.

Write for someone with no memory of the work — which in practice means every future session, and you in six months.

Then add one line to <docs>/DECISIONS.md, newest first (create it if absent):

# Decisions

- [<slug>](decisions/<slug>.md) — <one-line hook: what changed and why it mattered> (YYYY-MM-DD)

One line per feature. The index is for finding the record, not for summarising it. An index is only needed for the one-file-per-feature layout — a single ADR file is already its own index, and a numbered-record directory usually has a convention of its own.

4. Harvest guardrails

This is the natural moment to notice recurring mistakes, while the work is still fresh.

If a mistake was made and corrected during this feature — by you or caught by the user — check whether it is worth adding to the guardrail registry in lad-standards/references/guardrails.md. The bar is deliberately high: a lapse qualifies on the second sighting, or the first if it had real consequences. One-off slips are noise, and a registry that grows without pruning stops being read.

If an existing entry was observed again, update its sighting date. If entries have not been seen in a long time, propose retiring them.

5. Prune

Once the record is written, propose removing the working files:

• <docs>/<slug>/plan.md, context.md, plan_*.md, split.md

Ask before deleting. They are recoverable from git, but the user may still want them, and deletion is not yours to assume. If in doubt, leave them.

Also update STATUS.md if the project keeps one: the feature moves from in-progress to done, and anything it settled should supersede the older lines rather than being appended below them.

Report

Say which decision home you found and why — an existing ADR, a numbered-record directory, or nothing — then what you wrote there, any guardrail changes proposed, and what you suggest pruning. If you concluded the feature warranted no ADR entry, say that explicitly; silence reads as an oversight rather than a judgement.