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

S19: establish engineering repository

Browse Source
This commit is contained in:
Wanja Krah
2026-11-08 15:15:50 +01:00
commit c25ce11a1b
84 changed files with 6599 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

103
resources/skills/adr-brainstorm/SKILL.md Normal file
View File

@@ -0,0 +1,103 @@
---
name: adr-brainstorm
description: "Brainstorm with the user about a new ADR. Use when the user wants to stress-test their thinking, or uses any combination of 'adr' and 'brainstorm' in their trigger phrase."
---
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.
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.
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.
If the user, or the relevant ADR, indicates that an ADR is to supersede another ADR, read that ADR first.
## Explore decisions with the user
### Follow a design tree
Map the architectural question as a design tree: each decision may
introduce dependent decisions. Track which decisions are agreed,
open, awaiting factual investigation, or explicitly deferred.
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.
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.
### Establish facts before asking for decisions
Finding accessible facts is the agent's responsibility. Inspect relevant
code, configuration, specifications, ADRs, and authoritative documentation
before asking the user questions those sources can answer.
Distinguish observed facts, assumptions, recommendations, and decisions.
Cite sources for material factual claims and explain uncertainty where
evidence is unavailable or conflicting. Ask the user for requirements,
priorities, constraints, and knowledge unavailable from accessible sources.
Evaluate alternatives against the agreed requirements. Present credible
alternatives fairly, including drawbacks of the recommended approach.
Do not infer that an option is unsuitable merely because the current
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
available question at once if that would hinder discussion.
For decision questions, normally provide a recommended answer and its
reason. Where natural, phrase the question so "yes" clearly accepts that
recommendation. Make its scope explicit; avoid combining independent
decisions into one yes/no question.
Use open questions when discovering requirements or when a recommendation
would prematurely narrow the discussion. Allow disagreement, alternatives,
and back-and-forth exploration before seeking a decision.
### Leave architectural decisions with the user
The agent investigates, explains tradeoffs, challenges assumptions, and
recommends. The user selects the architectural approach and accepts its
material tradeoffs.
Do not treat silence, a factual answer, or agreement on one decision as
approval of other decisions. Preserve earlier agreements without repeatedly
requesting confirmation unless their meaning or supporting facts change.
At meaningful milestones, summarize the agreed decisions and remaining
questions. Before finalizing the ADR, confirm shared understanding of the
complete proposal. Keep recommendations and unresolved assumptions out of
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.
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 _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 _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 _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 _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.
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