ReddRadar
Agent skill
develop-adr
Creates an Architecture Decision Record following the Nygard format to document significant technical decisions, their context, and consequences. Use when making technical choices that affect system architecture, technology selection, or development patterns.
Install this agent skill to your Project
npx add-skill https://github.com/product-on-purpose/pm-skills/tree/main/skills/develop-adr
Metadata
Additional technical details for this skill
- author
- product-on-purpose
- category
- specification
- frameworks
-
[ "triple-diamond", "lean-startup", "design-thinking" ]
SKILL.md
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 follow
- Documenting the rationale for constraints or non-obvious approaches
- Preserving institutional knowledge about past decisions
Instructions
When asked to create an ADR, follow these steps:
-
Assign a Number and Title ADRs are numbered sequentially (ADR-001, ADR-002, etc.) for easy reference. The title should be a short noun phrase describing the decision, like "Use PostgreSQL for order data" or "Adopt React for frontend."
-
Set the Status New ADRs start as "Proposed." After team review, they become "Accepted," "Deprecated," or "Superseded by ADR-XXX." Status changes should be tracked.
-
Describe the Context Explain the circumstances that led to this decision. What problem are you solving? What forces are at play (technical constraints, team expertise, timeline, cost)? This section should help a reader who wasn't there understand why this decision was needed.
-
State the Decision Clearly articulate what you decided. Use active voice: "We will use..." rather than "It was decided..." Be specific about what is and isn't included in the decision.
-
Document the Consequences List the outcomes of this decision — positive, negative, and neutral. Good ADRs are honest about trade-offs. What becomes easier? What becomes harder? What new constraints or options does this create?
Output Format
Use the template in references/TEMPLATE.md to structure the output.
Quality Checklist
Before finalizing, verify:
- Title is a short, descriptive noun phrase
- Status is clearly indicated (Proposed/Accepted/Deprecated/Superseded)
- Context explains why this decision was needed
- Decision is stated clearly in active voice
- Consequences include both positive and negative outcomes
- ADR can stand alone without requiring other documents
Examples
See references/EXAMPLE.md for a completed example.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
product-on-purpose/pm-skills
init-project
Initialize projects with agentic coding structure. Use when setting up a new project, adding AI agent support to existing project, or when user says "init", "initialize", "setup project", or "scaffold". Creates AGENTS folder, documentation templates, and _NOTES scratch space.
product-on-purpose/pm-skills
init-project-jpkb
Initialize new JPKB projects with standardized documentation and folder structure. JPKB-specific version with category folders and fixed base path. Use when creating a new project in the jpkb repository, when the user says "init project", "new project", or when the target is the JPKB projects folder.
product-on-purpose/pm-skills
wrap-session
End-of-session documentation workflow that updates README, CHANGELOG, agent context files, and creates session logs. Use when wrapping up a working session, when asked to document session progress, when preparing handoff documentation, or when the user says "wrap up", "end session", "document progress", or "save session".
product-on-purpose/pm-skills
skill-template
product-on-purpose/pm-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.
product-on-purpose/pm-skills
utility-update-pm-skills
Validates internet access, compares the locally installed pm-skills version against the latest public release, and updates local files with conflict-aware overwrite-or-skip options. Produces an update report listing changed files, skipped files, and new capabilities. Use when you want to bring a local pm-skills installation up to date.
Didn't find tool you were looking for?