wanjakrah/landscape
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

ADR3 refinement

Browse Source
This commit is contained in:
Wanja Krah
2026-11-12 10:24:10 +01:00
parent dd8f0ce186
commit 39a3f1379c
3 changed files with 266 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
skills/adr-brainstorm/SKILL.md
View File

@@ -4,14 +4,16 @@ description: "Brainstorm with the user about a new ADR. Use when the user wants
---
An ADR is an Architecture Decision Record. Such a record contains a decision on the architecture or design for the application landscape the user is maintaining.
If an ADR-folder exists, read the README.md of that folder to get a full understanding of any specific rules and properties of how the user works with ADR's that might not be listed in this Skill.
If an ADR-folder exists, read the `README.md` of that folder to get a full understanding of any specific rules and properties of how the user works with ADRs that might not be listed in this Skill.
The goal of the ADR is to provide an architectural solution or a design solution for a given context. Therefor, two to four different approaches must be worked out with their pro's and con's, from which the user should select one as their preferred solution.
The goal of the ADR is to provide an architectural solution or a design solution for a given context. Therefore, two to four different approaches must be worked out with their pros and cons, from which the user should select one as their preferred solution.
Below, the brainstorm session is mapped out in multiple steps. Each step must be completed succesfully, before continuing to the next step. Success means reaching a shared understanding and whatever the step entitles as its success criteria.
Below, the brainstorm session is mapped out in multiple steps. Each step must be completed successfully before continuing to the next step. Success means reaching a shared understanding and meeting the success criteria defined for that step.
If the user, or the relevant ADR, indicates that an ADR is to supersede another ADR, read that ADR first.
Consider each ADR in the context of the application landscape, including active and future projects. State the decision's scope explicitly and consider its implications for other projects within that scope. Include project-specific context when it explains the problem that prompted the ADR or illustrates relevant constraints and tradeoffs. Keep those details focused so the ADR remains relevant and understandable to readers applying it to other projects.
## Explore decisions with the user
### Follow a design tree
@@ -24,12 +26,15 @@ Ask dependent questions only after their prerequisites are settled.
Revisit earlier decisions when new evidence changes their assumptions,
and explain which dependent decisions need reconsideration.
Number questions sequentially throughout the session using ❓ **Q1**, ❓ **Q2**, etc. as prefixes.
Number proposed answers within each question using ➡️ **P1**, ➡️ **P2**, etc. as prefixes. Restart proposal numbering for each question.
Keep the tree within the ADR's agreed scope. Suggest follow-up work
for independent topics rather than continually expanding the ADR.
A deferred topic must have a clear boundary and must not leave the
main decision ambiguous.
Finish when the user has agreed on the architectural decision and its material tradeoffs. Identify remaining implementation questions as follow-up work. Do not leave questions open that could materially change the chosen approach.
Finish exploring decisions when the user has agreed on the architectural decision and its material tradeoffs. Identify remaining implementation questions as follow-up work. Do not leave questions open that could materially change the chosen approach.
### Establish facts before asking for decisions
@@ -50,7 +55,7 @@ implementation uses something else.
### Keep the conversation collaborative
Use short rounds, usually one main question or a few closely related
questions. Number questions when asking more than one. Do not ask every
questions. Number every question. Do not ask every
available question at once if that would hinder discussion.
For decision questions, normally provide a recommended answer and its
@@ -79,25 +84,25 @@ the Decisions section until the user accepts them.
### Guide the process through steps
Coöperate with the user via the following steps. Communicate each step in which step you are, and what the step entails. Use the template adr-template.md as a template for the final ADR.
Work with the user through the following steps. At the start of each step, state which step you are on and what it entails. Use the template `adr-template.md` for the final ADR.
The _first step_ is to get to a shared understanding of the probived context and the problem area the user is in need for a decision. Success for step one means you can describe the context in one to fifty sentences.
The _first step_ is to get to a shared understanding of the provided context and the problem that requires an architectural decision. Success for step one means you can describe the context in one to fifty sentences.
The _second step_ is to get to two to four different architectural solutions or design solutions for the described context. Every solution needs a short description of one to fifty sentences and a list of one to ten pro's and one to ten con's. allow discussion of consequences when they affect the choice. Record them formally in _step four_, but don’t postpone discovering migration costs or operational burdens until after selecting an option.
Success for step two means there are more than one credible solutions with a set of relevant pro's and con's by which a user is able to choose, or not choose that solution for the next step.
The _second step_ is to get to two to four different architectural solutions or design solutions for the described context. Every solution needs a concise description, using no more than fifty sentences. Number each solution and include one to ten pros and one to ten cons. Allow discussion of consequences when they affect the choice. Record them formally in _step four_, but don’t postpone discovering migration costs or operational burdens until after selecting an option.
Step two succeeds when the user can compare at least two credible solutions using their relevant pros and cons.
The _third step_ is to pick the best solution. Ths user must decide what solution he prefers. The choosen solution will be presented as the ADR decision. A decision may branch into a small tree of related decisions, small meaning one to five levels deep. Make the architectural decision, its scope, and its material tradeoffs unambiguous; record remaining implementation questions as follow-up work. Success of step three means there is a shared understanding of the choosen solution and what it entails.
The _third step_ is to pick the best solution. The user must decide which solution they prefer. The chosen solution will be presented as the ADR decision. A decision may branch into a small tree of related decisions, with a maximum of five levels. Make the architectural decision, its scope, and its material tradeoffs unambiguous; record remaining implementation questions as follow-up work. Success of step three means there is a shared understanding of the chosen solution and what it entails.
The _fourth step_ is to make clear what the consequences will be for the application landscape. Success of step four means there is a clear understanding of the changes that should be made to software landscape and the way futurue work should be implemented.
The _fourth step_ is to make clear what the consequences will be for the application landscape. Success of step four means there is a clear understanding of the changes that should be made to the software landscape and the way future work should be implemented.
The _fifth step_ is fill out the other properties of the ADR that is required by the template. Succes of step five means the ID of the ADR is unique, the title is short and comprehandible, and gives the user an overall idea of what the ADR is about. If the ADR supersedes another ADR, that is listed as well.
Set the Expiration Date of when the ADR should be reviewd. This should be a relative date, to be made absolute by the user as soon as the user moves the ADR to APPROVED.
Finally, set the status to REFINED. It's up to the user to set the Status to either APPROVED - meaning the ADR is accepted and to be applied for all future work - or REJECTED - meaning the ADR is not accepted and should not be taken in consideration.
The _fifth step_ is to fill out the other properties of the ADR that are required by the template. Success of step five means the ID of the ADR is unique, the title is short and comprehensible and gives the user an overall idea of what the ADR is about. If the ADR supersedes another ADR, that is listed as well.
Set a review interval, such as six months after approval. The user converts this interval to an absolute expiration date when approving the ADR.
Finally, set the status to REFINED. It's up to the user to set the status to either APPROVED - meaning the ADR is accepted and to be applied to future work within its scope - or REJECTED - meaning the ADR is not accepted and should not be taken into consideration.
When updating the ADR with the result of the brainstorm, make it both easy to glanse through, as to read in full, meaning:
- stick to the template
- keep to the formatting as is custom for markdown-files
- high use of headers and sub-headers
- high use of bullit points, lists, and tables where applicable
- keep sentences short and precise where possible
- create images with ASCII-art where possible
When updating the ADR with the result of the brainstorm, make it easy to scan and to read in full, by following these guidelines:
- Stick to the template
- Follow standard Markdown formatting
- Use headings, lists, and tables where they improve readability
- Keep sentences short and precise where possible
- Use ASCII diagrams where they clarify the design