# Develop Design Rationale > Documents the reasoning behind design decisions including alternatives considered, trade-offs evaluated, and principles applied. Use when making significant UX decisions, aligning with stakeholders on design direction, or preserving design context for future reference. - **Type:** Skill - **Install:** `agentstack add skill-product-on-purpose-pm-skills-develop-design-rationale` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [product-on-purpose](https://agentstack.voostack.com/s/product-on-purpose) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [product-on-purpose](https://github.com/product-on-purpose) - **Source:** https://github.com/product-on-purpose/pm-skills/tree/main/skills/develop-design-rationale - **Website:** https://product-on-purpose.github.io/pm-skills/ ## Install ```sh agentstack add skill-product-on-purpose-pm-skills-develop-design-rationale ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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 decisions - When revisiting past decisions to understand original reasoning - During design system evolution to document pattern choices ## When NOT to Use - The decision is architectural or a technology selection -> use `develop-adr` (Nygard format) - You need stakeholder alignment on the overall solution direction -> use `develop-solution-brief` - You are documenting exploration findings rather than a decision -> use `develop-spike-summary` - The decision is trivially reversible and low-stakes: a rationale document adds ceremony; record the reasoning in the PR or ticket instead ## Instructions When asked to document design rationale, follow these steps: 1. **State the Decision** Begin with a clear, one-sentence summary of what design decision was made. This becomes the title and reference point for the document. 2. **Describe the Context** Explain the situation that prompted this decision. What problem were you solving? What constraints existed? What user needs informed the direction? Include relevant research findings. 3. **List Options Considered** Document at least 2-3 alternatives that were evaluated. For each option, describe what it would look like and its key characteristics. Be fair to all options.avoid strawmen. 4. **Define Evaluation Criteria** Specify how options were assessed: usability heuristics, technical feasibility, brand alignment, user research findings, business requirements, or design principles. 5. **Explain the Reasoning** Walk through why the chosen option best meets the criteria. Be explicit about trade-offs.what you gained and what you sacrificed. Acknowledge where the decision is reversible vs. irreversible. 6. **Document Trade-offs Accepted** Every design decision involves trade-offs. Name what you gave up and why it was acceptable. This honesty helps future teams understand constraints. 7. **Note Follow-up Considerations** Capture anything that needs attention later: metrics to watch, conditions that might warrant revisiting the decision, or related decisions to make. ## Output Format Use the template in `references/TEMPLATE.md` to structure the output. A complete rationale fills every template section: Decision Summary; Context; Options Considered; Evaluation; Decision Rationale; Trade-offs Accepted; Reversibility; Follow-up Considerations; Supporting Materials; and Decision History. ## Quality Checklist Before finalizing, verify: - [ ] Decision is clearly stated in one sentence - [ ] Context explains the "why now" and constraints - [ ] Multiple alternatives are documented fairly - [ ] Evaluation criteria are explicit - [ ] Reasoning addresses why chosen option beats alternatives - [ ] Trade-offs are honestly acknowledged - [ ] A reader who inherits this design can reconstruct why the chosen option won without asking anyone ## Examples See `references/EXAMPLE.md` for a completed example. ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [product-on-purpose](https://github.com/product-on-purpose) - **Source:** [product-on-purpose/pm-skills](https://github.com/product-on-purpose/pm-skills) - **License:** Apache-2.0 - **Homepage:** https://product-on-purpose.github.io/pm-skills/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-product-on-purpose-pm-skills-develop-design-rationale - Seller: https://agentstack.voostack.com/s/product-on-purpose - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.