develop-adr
This skill guides you through creating an Architecture Decision Record that captures the reasoning behind significant technical or architectural choices. It follows Michael Nygard's lightweight format to ensure decisions are documented with their context, rationale, and trade-offs—preserving institutional knowledge for future team members. Use it when selecting technologies, establishing development patterns, or documenting constraints that shape your system.
develop-adr documents significant technical decisions using the Nygard format to capture context, rationale, and consequences.
AI-generated summary based on this skill's SKILL.md
Decision gist · record as of 2026-07-24
develop-adr documents significant technical decisions using the Nygard format to capture context, rationale, and consequences. This skill guides you through creating an Architecture Decision Record that captures the reasoning behind significant technical or architectural choices. It follows Michael Nygard's lightweight format to ensure decisions are documented with their context, rationale, and trade-offs—preserving institutional knowledge for future team members. Use it when selecting technologies, establishing development patterns, or documenting constraints that shape your system.
Use it when
- develop-adr's template covers: Title, Status, Context (the issue or problem), Decision (what was chosen).
- develop-adr helps you document architectural decisions by providing a structured, numbered format that captures context and consequences.
Verify before relying
Read SKILL.md below before installing (7 files). Open directory: indexed for reading, not audited.
Install
product-on-purpose/pm-skills/develop-adr · repository language: JavaScript
Open directory. Skills are indexed for reading, not audited. Review a skill's body before installing it.
Frequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How to write an architecture decision record?
develop-adr guides you through creating an Architecture Decision Record using Michael Nygard's lightweight format. Start by numbering your ADR sequentially, then document the decision's context (what problem you faced), the decision itself (what you chose), consequences (trade-offs and impacts), and alternatives considered. Include the status (Proposed, Accepted, Deprecated, Superseded) so teams understand the decision's current standing. This structured approach ensures your reasoning is preserved for future team members.
What should an ADR template for technical decisions include?
develop-adr's template covers: Title, Status, Context (the issue or problem), Decision (what was chosen), Consequences (positive and negative outcomes), and Alternatives (options that were rejected). Some ADRs also include Rationale (why this choice) and Related Decisions (links to dependent ADRs). This format keeps documentation lightweight yet complete, making it easy for teams to understand not just what was decided, but why and what trade-offs were accepted.
How do I record architectural decisions with develop-adr?
develop-adr helps you document architectural decisions by providing a structured, numbered format that captures context and consequences. Create a new ADR file for each significant choice—whether it's technology selection, design patterns, or system constraints. Include the decision's background, what you chose, and the trade-offs involved. Store ADRs in version control alongside your code so they evolve with your system and remain accessible to all team members.
Why document technical choices and preserve decision reasoning?
develop-adr emphasizes that documenting technical choices preserves institutional knowledge when team members leave or projects shift focus. Recording the context and rationale behind decisions prevents teams from re-debating settled choices or unknowingly repeating past mistakes. ADRs capture trade-offs explicitly, helping future developers understand constraints and assumptions. This lightweight documentation format makes it practical to maintain a decision history without heavyweight process overhead.
What's the difference between ADR numbering and status tracking?
develop-adr uses sequential numbering (ADR-001, ADR-002, etc.) to create an immutable audit trail of decisions in chronological order. Status tracking marks each ADR as Proposed (under consideration), Accepted (approved), Deprecated (no longer used), or Superseded (replaced by another ADR). Together, numbering and status let teams quickly find decisions, understand their evolution, and see which choices remain active versus historical.
When should I use develop-adr for database selection?
develop-adr is ideal for documenting database selection decisions because these choices have long-term architectural impact. Create an ADR that explains the problem (scalability, consistency, query patterns), the database you chose, consequences (operational overhead, learning curve, cost), and alternatives you rejected. This record helps onboard new team members, justifies the choice to stakeholders, and provides a reference if you later need to reconsider the decision.
SKILL.md
Rendered from the published skill. Quoted content, verbatim.
<!-- PM-Skills | https://github.com/product-on-purpose/pm-skills | Apache 2.0 -->
Architecture Decision Record (ADR)
An Architecture Decision Record documents a significant technical decision along with its context and consequences. ADRs capture the "why" behind architectural choices so future team members understand the reasoning - especially important when they question why something was done a particular way. This skill follows Michael Nygard's lightweight ADR format.
When to Use
- Making significant technical decisions that affect system architecture
- Choosing between technology options (frameworks, databases, services)
- Establishing patterns that future development should
(truncated - see the full file via the links below)
File tree — 7 files
skills/develop-adr/HISTORY.md
skills/develop-adr/SKILL.md
skills/develop-adr/evals/output-scenarios/event-streaming.md
skills/develop-adr/evals/output-scenarios/search-datastore.md
skills/develop-adr/evals/trigger-fixtures.json
skills/develop-adr/references/EXAMPLE.md
skills/develop-adr/references/TEMPLATE.md
Let your AI agent find skills like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 56,283 agent skills by what they can do, searchable in plain language.
wish › “Document a significant technical or architectural decision with context and consequences”
Give your agent the search over MCP, or paste the wish link into any chat. No install? Search from any chat →
Related skills
ADR Author guides you through writing Architectural Decision Records that future developers and automated systems can actually enforce. It covers the full workflow from reading existing ADRs to drafting decisions at the right enforceability level—whether you need automated verification, human review, or reference-only documentation.
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.
Capture the outcomes of a focused technical or design investigation in a structured format that prevents knowledge loss and enables confident decision-making. This skill guides you through documenting the original question, methodology, evidence-backed findings, and actionable recommendation so stakeholders can proceed or pivot without re-litigating the exploration.
Develop Solution Brief generates a focused one-page document that frames your proposed solution, highlights essential features, and surfaces trade-offs for stakeholder alignment. Use it to pitch approach, bridge problem understanding to specification, or compare solution options without implementation details.
This skill generates Architecture Decision Records (ADRs) that capture the context, decision, and consequences of significant technical choices. It guides you through gathering essential information, selecting from three formats (MADR, Nygard, or Y-Statement), and produces a structured document that preserves reasoning for future engineers.
This skill guides you through building a concise problem framing document that establishes shared understanding before solution work begins. It walks through identifying affected users, surfacing pain points, connecting to business impact, and defining measurable success criteria—ensuring your team solves the right problem rather than jumping to how.
More skills deliver-prd (Apache-2.0) · architecture-decision-record (MIT) · architecture-decision-records (MIT) · adr-writer (MIT) · adr-writer (MIT)