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.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 805
- Forks
- 102
01 前言 Front Matter
- name
- develop-design-rationale
- license
- Apache-2.0
- metadata
- { "phase": "develop", "author": "product-on-purpose", "updated": 1781049600000, "version": "2.1.0", "category": "specification", "frameworks": [ "triple-diamond", "lean-startup", "design-thinking" ] }
- description
- 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.
02 资源文件 4
- 参考文档evals/trigger-fixtures.json4.0 KB
- 参考文档HISTORY.md731 B
- 参考文档references/EXAMPLE.md9.2 KB
- 参考文档references/TEMPLATE.md4.2 KB
03 SKILL.md 正文
<!-- 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 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:
-
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.
-
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.
-
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.
-
Define Evaluation Criteria Specify how options were assessed: usability heuristics, technical feasibility, brand alignment, user research findings, business requirements, or design principles.
-
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.
-
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.
-
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.
04 同仓库更多 Skills
utility-update-pm-skills
Checks for newer pm-skills releases, compares local vs. latest version, previews what would change, and updates local files after user confirmation. Generates a structured update report documenting changed files, new capabilities, and the value delta between versions. Use when you want to bring a local pm-skills installation up to date.
utility-slideshow-creator
Generates professional presentations from a JSON deck specification using 18 slide types with dark/light variants, content-to-layout decision logic, and calibrated character limits. Ships with a default professional theme.
utility-pm-workflow-orchestrator
Run an ordered sequence of pm-skills against one input, pausing for go/no-go and stopping on a failed or empty step. Accepts a saved prioritized action plan (Mode A) or an ad-hoc named chain (Mode B; the chain command routes here). Explicit invocation only; run --dry-run first while the native path is EXPERIMENTAL. To author a durable workflow instead, use utility-pm-workflow-builder.
utility-pm-workflow-builder
Guides a contributor from a workflow idea to a complete Workflow Implementation Packet (draft workflow file, draft workflow command, cross-cutting update checklist) in a staging area for review. Runs overlap analysis against the existing workflows with a Why Gate, then helps select and sequence skills with authored handoffs. Use when creating a new multi-skill workflow or promoting a repeated ad-hoc chain into a durable one. To build a single skill instead, use utility-pm-skill-builder; to run a sequence without authoring anything, use the chain command or utility-pm-workflow-orchestrator.
utility-pm-skill-validate
Audits an existing pm-skills skill against structural conventions and quality criteria. Produces a structured validation report with pass/fail checks, severity-graded findings, and actionable recommendations. Use when checking whether a skill meets repo standards before shipping or after making changes.
utility-pm-skill-iterate
Applies targeted improvements to an existing pm-skills skill based on feedback, validation reports, or convention changes. Reads current files, previews proposed changes, writes on confirmation, and suggests a version bump. Use when improving a skill after validation or feedback.