Distill an implementation plan/result into an Architecture Decision Record (ADR) after the work is done. Use this whenever the user asks to "turn this plan into an ADR", "write an ADR for what we just did", "計画をADR化", or similar phrasing that signals a completed implementation whose decisions deserve a durable record. The skill produces a concise ADR focused on decisions and rationale.
Implementation plans contain two kinds of content mixed together:
The job of this skill is to extract (2), discard (1), and leave behind a durable record that a teammate reading it in six months can actually use.
Only when the user explicitly asks for distillation after implementation is done. Typical triggers:
Do not run this skill proactively during planning or mid-implementation. The whole point is that distillation happens once the dust has settled and you know which decisions actually mattered.
Before writing, make sure you have:
docs/adr/, docs/decisions/, adr/, or similar. If none exists, ask the user where to put it (don't silently create a new convention). If one exists, follow its numbering and naming style.A good distillation is roughly 30–60% the length of the source plan. If the result is longer than ~70% of the original, you're still copying execution scaffolding. If it's under ~20%, you're probably dropping rationale that should be preserved.
Follow the existing convention in the repo if there is one. If not, use this default:
# ADR NNNN: <Short decision-oriented title>
## Context
<2–5 sentences. What problem does this address? What constraints
or forces made a decision necessary? No narrative of how you got here —
just the situation that demanded a choice.>
## Decision
<The chosen approach, stated plainly. Include the structural boundaries
(what lives where, what does NOT live where) and any invariants the
decision establishes.>
## Consequences
<What this forces or enables elsewhere. New APIs exposed, behaviors
now guaranteed, paths preserved, ordering requirements, etc.
Bullet points are fine here.>
## Rejected alternatives
<Each alternative considered, with a one-line reason it was rejected.
This section is often the most valuable — skipping it is the most
common way an ADR loses long-term value.>
Title the ADR around the decision, not the feature. "Display runtime GC architecture" is better than "Add xpra cleanup". The reader wants to know "what did we decide" not "what did we build".
If the repo already has ADRs, match their numbering scheme (zero-padded sequential is typical: 0007-display-runtime-gc.md). If there's no existing scheme, ask.
Source plan (abbreviated):
Problem
nas starts xpra-backed display sandboxes, but does not persist enough runtime metadata to GC orphaned xpra resources after crashes...
Proposed approach
- Introduce a display runtime registry...
- Extend the display lifecycle so DisplayService.startXpra() records enough information...
- Wire GC into the requested triggers...
- Add tests around registry GC...
Todos
- display-runtime-registry — Add src/display/registry.ts ...
- display-service-bookkeeping — Update src/services/display.ts ...
- ui-cleanup-hooks — Update src/ui/data.ts ...
- xpra-gc-tests — Add focused tests ...
Notes
- Preserve the current display runtime location...
- Prefer killing the auto-attach client before the xpra server...
- The GC sweep should be conservative about live sessions: metadata alone is not enough, and probes alone are not enough...
Distilled ADR:
# ADR 0007: Display runtime GC architecture
## Context
xpra-backed display sandboxes leak resources (server/attach processes,
X11 sockets, session dirs) on crashes or partial startup failures.
GC is needed at session startup, stopContainer, and cleanContainers.
## Decision
GC lives behind a display runtime registry, not in DisplayStage.
DisplayStage stays an orchestration boundary; filesystem and process
teardown belong to display-focused modules.
Session matching uses both persisted metadata and live probes
(PID liveness, socket/session-dir existence). Neither alone is