develop-design-rationale
Capture the "why" behind design choices by documenting decision context, alternatives evaluated, and reasoning that led to your solution. This skill preserves institutional knowledge about design decisions, helping teams onboard to existing choices and revisit past reasoning when needed.
develop-design-rationale documents the reasoning, alternatives, and trade-offs behind significant UX design decisions.
AI-generated summary based on this skill's SKILL.md
Install
product-on-purpose/pm-skills/develop-design-rationale · repository language: JavaScript
git clone https://github.com/product-on-purpose/pm-skills
cp -r pm-skills/skills/develop-design-rationale ~/.claude/skills/develop-design-rationalenpx skillfed install product-on-purpose/pm-skills/develop-design-rationaleFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How to document design decisions and reasoning?
develop-design-rationale helps you systematically capture the "why" behind UX choices. Start by identifying the decision context—what problem prompted the choice, who was involved, and what constraints applied. Document the alternatives you evaluated, the trade-offs you accepted, and the reasoning that led to your final solution. Include relevant data, user research, or business factors that influenced the outcome. This structured approach ensures your design rationale is clear, traceable, and useful for future reference.
What should a design rationale template include?
develop-design-rationale emphasizes capturing decision context, alternatives considered, and the reasoning behind your choice. A strong template covers: the design decision itself, the problem it addresses, alternatives you evaluated and why you rejected them, key trade-offs you accepted, supporting evidence or research, stakeholders involved, and the date documented. This structure makes your rationale easy to review with stakeholders, onboard new team members, and revisit when circumstances change or questions arise later.
Why preserve design context and decision history?
develop-design-rationale recognizes that design decisions carry institutional knowledge that fades quickly without documentation. Preserving context helps new team members understand not just what was chosen, but why—reducing re-litigation of settled choices and accelerating onboarding. It also protects against knowledge loss when team members leave and enables teams to revisit past reasoning when requirements shift, making it easier to decide whether to adapt an existing solution or reconsider the original trade-offs.
How can design rationale help with stakeholder alignment?
develop-design-rationale prepares your design reasoning for stakeholder review by making your decision process transparent and defensible. When you document alternatives considered, trade-offs accepted, and the reasoning behind your choice, stakeholders can see the full picture rather than just the final outcome. This clarity reduces pushback based on misunderstanding, enables informed discussion about whether trade-offs remain acceptable, and builds confidence that the design was thoughtfully considered rather than arbitrary.
What trade-offs should design rationale capture?
develop-design-rationale emphasizes documenting the compromises inherent in any design choice. Capture what you gained with your solution and what you gave up—whether that's simplicity versus power, performance versus flexibility, or cost versus quality. Explain why you weighted those trade-offs the way you did given your context, constraints, and user needs. This honesty about trade-offs helps teams understand the decision's limits and makes it easier to revisit the choice if priorities shift or new information emerges.
How does design rationale differ from an architecture decision record?
develop-design-rationale focuses on capturing UX and interaction design reasoning—the "why" behind choices about user experience, interface patterns, and interaction flows. While both preserve decision history, design rationale emphasizes user impact, alternatives evaluated, and design thinking, whereas architecture decision records typically address technical system structure. Both serve similar preservation and alignment goals but operate at different levels; you may use both to document different aspects of a complex product decision.
SKILL.md
rendered from the published skill — quoted content, verbatim
<!-- PM-Skills | https://github.com/product-on-purpose/pm-skills | Apache 2.0 -->
Design Rationale
A design rationale document captures the "why" behind design decisions.the context, constraints, alternatives considered, and reasoning that led to a particular solution. While designs themselves show what was built, rationale documents preserve institutional knowledge about why it was built that way.
When to Use
- When making significant UX decisions that affect user experience
- Before design reviews to prepare stakeholder discussions
- When multiple valid approaches exist and the choice needs justification
- To onboard new team members to existing design
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 5 files
skills/develop-design-rationale/HISTORY.md
skills/develop-design-rationale/SKILL.md
skills/develop-design-rationale/evals/trigger-fixtures.json
skills/develop-design-rationale/references/EXAMPLE.md
skills/develop-design-rationale/references/TEMPLATE.md