Open
Conversation
Add a new skill for creating and managing ADRs using the MADR format. Includes three slash commands for different workflows: - /adr-create: Create ADR from user-provided plan - /adr-from-current: Convert active plan (PLAN.md/todos) to ADR - /adr-interview: Document past decisions through structured interview Features: - Automatic numbering and index management - MADR template with comprehensive sections - Status lifecycle tracking (proposed → accepted → deprecated/superseded) - Detailed resource files for each command workflow - Integrated guidance for when to use ADRs Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
In step 3 of all three commands (adr-create, adr-from-current, adr-interview), if the adr/ directory doesn't exist or is empty, ask the user if there's a different location for ADRs or if they want to initialize the ADR system in adr/. This handles cases where projects may have ADRs in non-standard locations or need initial setup. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Major fixes: - Fixed order of operations: check location before reading template - Added official MADR template as fallback (from joelparkerhenderson/architecture-decision-record) - Added README template for initialization - Added proper initialization flow with user consent - Added custom ADR location support throughout workflow - Added git repo root detection (falls back to working directory) - Added validation steps for numbers, titles, and sections - Clarified to show full file content after creation Structural improvements: - Removed redundant resource workflow files (adr-create.md, adr-from-current.md, adr-interview.md) - Consolidated all workflow logic into SKILL.md (following pattern from other skills) - Added comprehensive error handling section - Updated references to use proper templates Validation additions: - Check for duplicate ADR numbers - Validate kebab-case format for titles - Validate title length (<50 chars) - Check for duplicate index entries Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
…nsequences Reorganized Phase 3-5 of the interview to: - Phase 3: Gather pros/cons for ALL options first (theoretical trade-offs) - Phase 4: Understand which was chosen and why - Phase 5: Capture real-world consequences (what actually happened) This prevents asking about consequences before fully exploring all options, and makes a clearer distinction between predicted trade-offs (pros/cons) and actual outcomes (consequences). Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Added Question 8 to Phase 4: "What was the expected outcome or goal when you made this decision? What were you hoping to achieve?" This captures the intended outcome/justification before asking about real-world consequences, providing better context for the decision and distinguishing between: - Why the option was chosen (Q7) - What outcome was expected (Q8) - What actually happened (Q9-12) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
All fixes from second critical review:
1. Added example-adr.md showing complete MADR structure
2. Fixed hardcoded adr/ path to {adr_location} in interview confirmation
3. Changed README references to use structure (not copy with project name)
4. Clarified index entry format: [ADR-NNNN: Title](file.md) - One-line summary
5. Moved title validation to appropriate points in each workflow
6. Specified using Read tool to show file content
7. Added comprehensive template placeholder replacement guidance
8. Fixed interview flow: create file, show draft, get revisions, save final
9. Added pros/cons mapping guidance - each option gets subsection with its points
10. Replaced all hardcoded adr/ references with {adr_location} variable
11. Added guidance for handling many options, unclear memory, informal evaluation
Key improvements:
- Template placeholder replacement now explicit (remove brackets, comments, etc.)
- Index entries clearly defined with title and one-line summary
- Title validation happens before proceeding with ADR creation
- Interview properly distinguishes draft vs finalized state
- Pros/cons properly map to individual option blocks in MADR structure
- Consistent use of {adr_location} throughout for custom paths
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
All fixes from third critical review:
1. Fixed {location} → {adr_location} inconsistency in initialization
2. Added pros/cons collection to /adr-create workflow:
- Ask for pros/cons of each alternative if not provided
- Guide user through systematic pros/cons gathering
3. Clarified one-line summary generation:
- Claude generates from Decision Outcome section
- Format: "Adopt MADR format for documenting decisions"
4. Added file reading step to /adr-create before user questions:
- Ask user if they have a plan file to read
- Extract information from file first
- Only ask remaining questions for missing info
5. Simplified redundant number validation:
- Check for similar titles instead of exact filename match
- Use glob pattern [0-9][0-9][0-9][0-9]-*.md to match only ADRs
6. Fixed example interaction to show Read tool result
7. Set past decisions to "accepted" consistently (not "typically")
8. Specified N/A for optional sections with no content
9. Specified deciders as comma-separated names
10. Clarified technical story can link in both Technical Story and Links
11. Added specific glob pattern [0-9][0-9][0-9][0-9]-*.md
12. Index insertion before Contributing/License sections
13. Created dedicated "Template Placeholder Replacement" section
14. Updated interview mapping to reference phases not question numbers
Key improvements:
- File reading capability in /adr-create workflow
- Systematic pros/cons gathering for all commands
- Dedicated template replacement section (DRY principle)
- Phase-based mapping (resilient to question changes)
- Clear one-line summary generation process
- Comprehensive example interaction showing full flow
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
gadenbuie
reviewed
Feb 26, 2026
gadenbuie
reviewed
Feb 26, 2026
gadenbuie
reviewed
Feb 26, 2026
Collaborator
gadenbuie
left a comment
gadenbuie
left a comment
There was a problem hiding this comment.
Since ADRs aren't a general shared practice in Open Source at Posit, I think it'd be useful to outline how you use this skill, how it improves your interactions with Claude, how it fits into a general workflow, etc.
I also think we should probably not include it in the open-source plugin. I've been thinking that not every skill needs to be bundled into a plugin. We could just move this to the top-level of the repo and mention it separately in an "Other Skills" section. Users would install the skill with the direct npx skills add method of installation.
Author
Sorry, my previous reply to this didn't send! It seems unlikely to me that someone would discover ADRs through this skill, so I'm not sure how many eyes more explanation would get. I moved it out of the open-source grouping into the posit-dev skills, so perhaps that's a better home. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This skill helps Claude: