diff --git a/skills/adr-brainstorm/SKILL.md b/skills/adr-brainstorm/SKILL.md index f47e4d3..6ef44da 100644 --- a/skills/adr-brainstorm/SKILL.md +++ b/skills/adr-brainstorm/SKILL.md @@ -1,7 +1,6 @@ --- 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. -dependencies: "Dependend on the Grill-me skill by Matt Pocock" +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. @@ -11,18 +10,83 @@ The goal of the ADR is to provide an architectural solution or a design 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. -When interviewing the user, use the skill-tool "grilling" that comes with the grill-me-skill to come to a shared understanding. If the grill-me skill is missing, ask the user for permission to install the grill-me skill by Matt Pocock. - 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. Any consequences to the current landscape that may be discussed, should be kept for _step four_. +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 desision. A decision may branch into a small tree of related desisions, small meaning one to five levels deep. Make sure that you come to a shared understanding of what the desision entails, what relates to it, an when it fully described, clear of any ambiguity. 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. 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. diff --git a/skills/adr-brainstorm/adr-template.md b/skills/adr-brainstorm/adr-template.md index bd751c6..7afb962 100644 --- a/skills/adr-brainstorm/adr-template.md +++ b/skills/adr-brainstorm/adr-template.md @@ -1,4 +1,4 @@ -**ID:** \ +**ID:** \ **Title:** \ **Supersedes:** - \ **Status:** NEW \