What is the design-rationale skill?
The design-rationale skill is a SKILL.md in the designer-toolkit plugin of Owl-Listener's designer-skills repository. It has an AI coding agent write a seven part rationale, from the decision and its context to options, evidence, reasoning, trade-offs and a validation plan, linked to user needs and goals.
The design-rationale skill lives in the designer-toolkit plugin of Owl-Listener's designer-skills pack. The SKILL.md casts the agent as an expert in articulating the reasoning behind design decisions, and asks for rationale that connects each decision to evidence, principles and goals.
Its description limits it to decisions that need defending in writing. For a live conversation it names design-negotiation, so this skill covers the written case and design-negotiation covers the live conversation.
The seven part structure
- Decision: what was chosen, stated specifically.
- Context: the problem or need behind it, and the constraints.
- Options considered: the alternatives explored, briefly described.
- Evidence: user research, data, best practices, competitive analysis or usability testing.
- Reasoning: why this option beat the others, tied to user needs, business goals, design principles and technical feasibility.
- Trade-offs: the known compromises and what was deprioritized.
- Validation plan: the metrics or feedback that will confirm the decision was right.
When to write rationale
- Major design direction decisions.
- Departures from established patterns, such as a design system's patterns.
- Controversial or debated choices.
- Decisions that will be questioned later.
- Changes from previous approaches.
Who the design-rationale skill is for
Best for
- Designers who need a decision explained in a design review, such as an structured team critique.
- Teams that reference the reasoning in their handoff documentation.
- Anyone whose choices get questioned months later and needs a record specific enough to still make sense.
Not for
- Defending a decision in a live conversation. The description points to design-negotiation for that.
- Choices nobody will question. The skill targets decisions that are major, controversial or will be questioned later.
How to install Design Rationale Skill: Write Down Why You Chose It
/plugin marketplace add Owl-Listener/designer-skillsAdd the marketplace
Enter the command above in your AI coding agent. It points the agent at the repository, and no plugin installs at this stage.
Install the plugin
Run
/plugin install designer-toolkit@designer-skills. designer-toolkit is the plugin that holds this skill, and the Discover tab under/pluginoffers the same choice.Gemini CLI route
Each plugin is also a Gemini CLI extension. Clone the repository to a temporary folder, create
.gemini/extensionsin your project root, and copy the repository's.gemini/extensionscontents into it.Name the decision
Tell the agent which decision to document and share the options and evidence you already have. It fills the seven parts from that.
Check that it loaded
Ask for a rationale for one design decision. Expect seven headed parts, from Decision through Validation Plan.
Key features
- Seven part structureEvery rationale runs decision, context, options considered, evidence, reasoning, trade-offs and validation plan, in that order.
- Specific decision statementThe first part asks the agent to be specific about what was chosen instead of describing the area in general terms.
- Constraints in contextThe context part captures the problem or need that prompted the decision and the constraints that applied.
- Alternatives on recordOptions considered gives each explored alternative a brief description, so readers see what was not chosen.
- Evidence sourcesEvidence can be user research, data, best practices, competitive analysis or usability testing.
- Reasoning tied to goalsWhy this option over the others is connected to user needs, business goals, design principles and technical feasibility.
- Honest trade-offsThe skill asks for the known compromises and what was deprioritized and why.
- Validation planEach rationale states the metrics or feedback that will confirm the decision was right.
- Quality checklistGood rationale connects to user needs, references evidence or principles, acknowledges alternatives, stays specific enough to be useful months later and is written for its audience.
Frequently asked questions
What is the design-rationale skill?
It is a SKILL.md in the designer-toolkit plugin of Owl-Listener's designer-skills repository. It has an AI coding agent write rationale that connects a design decision to evidence, user needs, business goals and principles, using a seven part structure that ends with a validation plan.
How do I install design-rationale?
Run /plugin marketplace add Owl-Listener/designer-skills, then /plugin install designer-toolkit@designer-skills. The skill is part of the designer-toolkit plugin. The Discover tab under /plugin offers the same choice, and Gemini CLI users can copy the repository's extensions folder. The same plugin also ships /designer-toolkit:write-rationale, which writes rationale for a set of decisions.
What does a design rationale include?
The skill structures it as decision, context, options considered, evidence, reasoning, trade-offs and validation plan. Each part has a prompt, such as what alternatives were explored, what informed the decision, what compromises were accepted and which metrics or feedback will confirm the choice was right.
When should I write design rationale?
The skill lists major design direction decisions, departures from established patterns, controversial or debated choices, decisions that will be questioned later and changes from previous approaches. Its best practice is to write rationale during the decision, not after, and to keep it concise but complete.
Where should design rationale be stored?
The skill's best practices say to store rationale alongside the design files, reference it in handoff documentation and use it in design reviews to explain choices. It also says to write rationale during the decision, not after, and to keep it concise but complete.
What license does design-rationale use?
It is MIT licensed, as is the whole Owl-Listener/designer-skills repository. The pack holds 273 skills and 76 commands across 33 plugins, and design-rationale is one of the skills in the designer-toolkit plugin. The nine design practice plugins, designer-toolkit among them, ship from this repository.
How is design-rationale different from design-negotiation?
The design-rationale description limits it to decisions that need defending in writing. For a live conversation it points to design-negotiation. The rationale skill itself produces a seven part written record: decision, context, options considered, evidence, reasoning, trade-offs and validation plan.