diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 6747fc3..63d8110 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -15,8 +15,10 @@ "source": "./", "strict": false, "skills": [ + "./posit-dev/adr", "./posit-dev/critical-code-reviewer", - "./posit-dev/describe-design" + "./posit-dev/describe-design", + "./posit-dev/pr-create" ] }, { diff --git a/README.md b/README.md index c282213..eb08636 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@ Claude Skills extend Claude's capabilities with specialized knowledge and workfl General-purpose developer skills useful across any language, project type, or context. +- **[adr](./posit-dev/adr/)** - Architecture Decision Records (ADR) management using the MADR format. Create ADRs from plans, convert active plans to ADRs, or interview to document past decisions - **[critical-code-reviewer](./posit-dev/critical-code-reviewer/)** - Conduct rigorous, adversarial code reviews identifying security holes, lazy patterns, edge case failures, and bad practices across Python, R, JavaScript/TypeScript, SQL, and front-end code - **[describe-design](./posit-dev/describe-design/)** - Research a codebase and create architectural documentation describing how features or systems work, with Mermaid diagrams and stable code references suitable for humans and AI agents - **[pr-create](./posit-dev/pr-create/)** - Creates a pull request from current changes, monitors GitHub CI, and debugs any failures until CI passes diff --git a/posit-dev/README.md b/posit-dev/README.md index c749d22..1d1b6f7 100644 --- a/posit-dev/README.md +++ b/posit-dev/README.md @@ -4,6 +4,7 @@ General-purpose developer skills useful across any language, project type, or co ## Skills +- **[adr](./adr/)** - Architecture Decision Records (ADR) management using the MADR format - **[critical-code-reviewer](./critical-code-reviewer/)** - Rigorous, adversarial code review across Python, R, JavaScript/TypeScript, SQL, and front-end code - **[describe-design](./describe-design/)** - Research a codebase and create architectural documentation with Mermaid diagrams - **[pr-create](./pr-create/)** - Creates a pull request from current changes, monitors GitHub CI, and debugs any failures until CI passes diff --git a/posit-dev/adr/SKILL.md b/posit-dev/adr/SKILL.md new file mode 100644 index 0000000..cfa6d2f --- /dev/null +++ b/posit-dev/adr/SKILL.md @@ -0,0 +1,207 @@ +--- +name: adr +description: Architecture Decision Records (ADR) management. Creates, documents, and manages ADRs using the MADR format. Use when the user says "create adr", "document decision", "make an adr", or wants to formally capture architectural decisions. Intelligently routes between three workflows - converting an active plan, creating from a user-provided plan or description, or conducting an interview for past decisions. +compatibility: Designed for Claude Code +metadata: + author: Posit + version: "1.0" +license: MIT +--- + +# Architecture Decision Records (ADR) Skill + +This skill helps create and manage Architecture Decision Records (ADRs) using the MADR (Markdown Any Decision Record) format. ADRs document important architectural decisions with their context, alternatives considered, and consequences. + +## Command: /adr + +This skill provides a single `/adr` command that intelligently routes to the appropriate workflow based on the situation. + +### Initial Routing Logic + +When `/adr` is invoked: + +1. **Check for active plan**: Look for Claude's current working plan (PLAN.md, active todo list, or recent planning discussion in conversation) + +2. **Determine the scenario** and route accordingly: + + **Scenario A - Active Plan Exists**: If an active plan is detected → **Route to "Convert Current Plan" flow** + + **Scenario B - User Provides Context**: If no active plan but user mentions a decision/plan → **Route to "Create from Plan" flow** + + **Scenario C - Need More Information**: If neither applies → **Ask routing question** + +3. **Routing Question** (when needed): + + "I'll help you create an ADR. Which scenario best describes what you need? + + 1. **Document a plan or decision** - You have details about a decision to document + 2. **Interview me about a past decision** - Walk me through questions to capture a decision that was already made + + Which would you prefer?" + + - If user chooses option 1 → Route to "Create from Plan" flow + - If user chooses option 2 → Route to "Interview" flow + +### Flow A: Convert Current Plan + +Convert Claude's currently active plan (PLAN.md or todo list) into an Architecture Decision Record. + +**When to use**: Detected active plan in the conversation or project files. + +#### Workflow + +1. **Setup ADR System** (see "Common Setup Steps" section below) + - Determine repository root and ADR location + - Initialize if needed (with user consent) + +2. **Locate the current plan** + + Check for an active plan in these locations (in order): + - `PLAN.md` in the repository root + - Active todo list from the current session + - Recent planning discussion in the conversation + + If no plan is found, inform the user: "I don't see an active plan in this conversation. Would you like to: + 1. Provide a plan or describe a decision (I'll use the 'Create from Plan' flow) + 2. Walk through an interview about a past decision?" + + Route to the appropriate flow based on their choice. + +3. **Read template and determine ADR number** (see "Common Setup Steps") + +4. **Analyze the plan** + + Extract from the current plan: + - **Problem Statement**: What issue is the plan addressing? + - **Proposed Solution**: What approach does the plan take? + - **Implementation Steps**: These often reveal decision drivers + - **Alternatives**: Any options mentioned or implied + +5. **Transform plan into ADR format** + + Plans often lack some ADR elements. Ask the user: + - "What alternatives did you consider before this plan?" + - "Who should be listed as deciders?" + - "What are the potential downsides of this approach?" + + **Status determination**: + - If the plan is actively being implemented → status is "accepted" + - If the plan is awaiting approval → status is "proposed" + - If unclear, ask: "Is this decision already approved, or awaiting review?" + +7. **Generate and present the ADR** (see "Common Generation Steps") + +8. **Handle the plan file** + + Ask the user: "The plan has been converted to ADR. Would you like me to: + - Keep PLAN.md as-is (for continued implementation tracking) + - Delete PLAN.md (if implementation is complete) + - Archive PLAN.md somewhere else" + +### Flow B: Create from Plan + +Create an Architecture Decision Record from a plan or decision description provided by the user. + +**When to use**: User has a plan document or wants to describe a decision directly. + +#### Workflow + +1. **Setup ADR System** (see "Common Setup Steps" section below) + +2. **Get the plan from the user** + + Ask: "Do you have a plan document or file I should read, or would you prefer to describe the decision directly?" + + If user provides a filename: + - Read the file + - Extract as much information as possible from the file content + + If no file or if file doesn't contain complete information, ask: "Please describe the decision or plan you want to document as an ADR. Include: + - What problem are you solving? + - What options did you consider? + - What did you decide and why?" + +3. **Read template and determine ADR number** (see "Common Setup Steps") + +4. **Extract information from the plan** + + Map user's information to ADR sections: + + | User's Plan Info | → | ADR Section | + |------------------|---|-------------| + | Decision name | → | Title (concise, use kebab-case for filename) | + | Situation/problem | → | Context and Problem Statement | + | Requirements/constraints | → | Decision Drivers | + | Alternatives considered | → | Considered Options | + | Chosen approach | → | Decision Outcome | + | Why this was chosen | → | Decision Outcome justification | + | Benefits | → | Positive Consequences | + | Drawbacks/risks | → | Negative Consequences | + | Related issues/PRs | → | Technical Story + Links section | + +5. **Validate and fill gaps** (see "Common Validation Steps") + + Ask clarifying questions if needed: + - "Who are the deciders for this decision?" + - "For each option, what were the pros and cons?" + - "What are the potential downsides of this approach?" + +6. **Generate and present the ADR** (see "Common Generation Steps") + +### Flow C: Interview for Past Decision + +Guide the user through an interactive interview to document a past architectural decision. + +**When to use**: User wants to document a decision that was already made in the past. + +**Purpose**: Sometimes decisions were made in the past without formal documentation. This flow helps retroactively capture those decisions through a structured conversation. + +**Detailed interview script**: See `references/interview-flow.md` for the complete phase-by-phase interview questions and workflow. + +#### High-Level Workflow + +1. **Conduct structured interview** (7 phases covering context, alternatives, outcome, and consequences) + - See `references/interview-flow.md` for complete question script + +2. **Setup ADR system** (see "Common Setup Steps") + +3. **Synthesize answers into ADR format** + - Map interview responses to MADR sections + - Set status to "accepted" (past decisions already in effect) + +4. **Generate and present the ADR** (see "Common Generation Steps") + +## Common Steps (Shared Across All Flows) + +All three workflows share standard procedures for setup, validation, and generation. See `references/common-steps.md` for complete details on: +- **Setup**: Determining ADR location, initializing system, reading template, numbering +- **Validation**: Title format, length, and duplicate checking +- **Generation**: Creating ADR file, updating index, presenting results + +## Guidelines and Best Practices + +For complete guidelines including: +- File structure and naming conventions +- ADR status lifecycle +- When to write an ADR +- Template placeholder replacement rules +- Important rules to follow +- Error handling and edge cases + +See `references/guidelines.md` + +**Key reminders:** +- Always use kebab-case for filenames (e.g., `0001-use-typescript.md`) +- Always update the index in README.md +- Always ask clarifying questions rather than guessing +- Always show the user the file content using Read tool before finalizing + +## Reference Files + +The skill includes reference files in the `references/` directory: +- `_template.md` - Official MADR template (fallback if project has none) +- `README-example.md` - Example README structure for initializing new ADR directories +- `example-adr.md` - Fully worked example ADR showing proper MADR structure and content +- `common-steps.md` - Standard setup, validation, and generation procedures used across all workflows +- `guidelines.md` - Complete ADR guidelines, naming conventions, template placeholders, and error handling +- `interview-flow.md` - Detailed interview script with all phases and questions for Flow C diff --git a/posit-dev/adr/references/README-example.md b/posit-dev/adr/references/README-example.md new file mode 100644 index 0000000..0c6c4d8 --- /dev/null +++ b/posit-dev/adr/references/README-example.md @@ -0,0 +1,79 @@ +# Architecture Decision Records (ADRs) + +This directory contains Architecture Decision Records (ADRs) for this project. + +## What is an ADR? + +An Architecture Decision Record captures an important architectural decision made along with its context and consequences. ADRs help teams: + +- **Document** significant decisions for future reference +- **Communicate** decisions to team members and stakeholders +- **Understand** the reasoning behind existing architecture +- **Onboard** new contributors by explaining "why" things are the way they are + +## ADR Format + +We use the [MADR](https://adr.github.io/madr/) (Markdown Any Decision Record) format. Each ADR includes: + +- **Status**: proposed, accepted, rejected, deprecated, or superseded +- **Context**: The situation and problem being addressed +- **Decision Drivers**: Factors influencing the choice +- **Options Considered**: Alternatives that were evaluated +- **Decision Outcome**: The chosen option and its justification +- **Consequences**: Both positive and negative outcomes + +See [`_template.md`](_template.md) for the full template. + +## Naming Convention + +ADRs follow the naming pattern: + +``` +NNNN-.md +``` + +Where: +- `NNNN` is a 4-digit sequence number (0001, 0002, etc.) +- `` is a short, descriptive title + +Examples: +- `0001-use-rest-api.md` +- `0002-adopt-microservices.md` +- `0003-use-postgresql.md` + +## When to Write an ADR + +Write an ADR when: + +- Adding a new major feature or component +- Changing existing architectural patterns +- Making technology or dependency choices +- Establishing new conventions or standards +- Deprecating or removing significant functionality + +You probably don't need an ADR for: + +- Bug fixes +- Minor refactoring +- Documentation updates +- Routine dependency updates + +## ADR Lifecycle + +``` +proposed → accepted → [deprecated | superseded] + ↓ + rejected +``` + +- **proposed**: Initial state, under review +- **accepted**: Decision approved and in effect +- **rejected**: Decision not approved +- **deprecated**: Decision no longer relevant +- **superseded**: Replaced by a newer ADR (link to the new one) + +## Index + + + +*No ADRs yet. Create the first one!* diff --git a/posit-dev/adr/references/_template.md b/posit-dev/adr/references/_template.md new file mode 100644 index 0000000..25696bb --- /dev/null +++ b/posit-dev/adr/references/_template.md @@ -0,0 +1,72 @@ +# [short title of solved problem and solution] + +* Status: [proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005](0005-example.md)] +* Deciders: [list everyone involved in the decision] +* Date: [YYYY-MM-DD when the decision was last updated] + +Technical Story: [description | ticket/issue URL] + +## Context and Problem Statement + +[Describe the context and problem statement, e.g., in free form using two to three sentences. You may want to articulate the problem in form of a question.] + +## Decision Drivers + +* [driver 1, e.g., a force, facing concern, …] +* [driver 2, e.g., a force, facing concern, …] +* … + +## Considered Options + +* [option 1] +* [option 2] +* [option 3] +* … + +## Decision Outcome + +Chosen option: "[option 1]", because [justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force force | … | comes out best (see below)]. + +### Positive Consequences + +* [e.g., improvement of quality attribute satisfaction, follow-up decisions required, …] +* … + +### Negative Consequences + +* [e.g., compromising quality attribute, follow-up decisions required, …] +* … + +## Pros and Cons of the Options + +### [option 1] + +[example | description | pointer to more information | …] + +* Good, because [argument a] +* Good, because [argument b] +* Bad, because [argument c] +* … + +### [option 2] + +[example | description | pointer to more information | …] + +* Good, because [argument a] +* Good, because [argument b] +* Bad, because [argument c] +* … + +### [option 3] + +[example | description | pointer to more information | …] + +* Good, because [argument a] +* Good, because [argument b] +* Bad, because [argument c] +* … + +## Links + +* [Link type] [Link to ADR] +* … diff --git a/posit-dev/adr/references/common-steps.md b/posit-dev/adr/references/common-steps.md new file mode 100644 index 0000000..edce831 --- /dev/null +++ b/posit-dev/adr/references/common-steps.md @@ -0,0 +1,72 @@ +# Common Steps (Shared Across All Flows) + +These are the standard procedures used across all three ADR creation workflows. + +## Common Setup Steps + +### Determine repository root and ADR location + +1. Find the git repository root using `git rev-parse --show-toplevel` +2. If not a git repo, use the current working directory +3. Check if `adr/` directory exists at this location +4. If `adr/` doesn't exist or is empty, ask: "I don't see any existing ADRs in `adr/`. Is there a different location where ADRs are stored in this project, or should I initialize the ADR system in `adr/`?" +5. Store the confirmed ADR location as `{adr_location}` for use in subsequent steps + +### Initialize ADR system if needed + +If the user wants to initialize in a new location, ask for consent: "I'll initialize the ADR system by creating: +- `{adr_location}/` directory +- `{adr_location}/README.md` with documentation +- `{adr_location}/_template.md` with the MADR template + +Should I proceed?" + +If yes: +- Create the directory +- Create `{adr_location}/README.md` using the structure from skill's `references/README-example.md` +- Create `{adr_location}/_template.md` copying content from skill's `references/_template.md` + +### Read the template + +Read `{adr_location}/_template.md` to understand the expected format. If not found, use the template from skill's `references/_template.md`. + +### Determine the next ADR number + +- List existing ADRs in the confirmed location +- Find files matching pattern `[0-9][0-9][0-9][0-9]-*.md` (excludes _template.md, README.md) +- If no ADRs exist, use `0001` +- Otherwise, increment from the highest existing number + +## Common Validation Steps + +### Validate title + +- Check it's in kebab-case format (e.g., "use-typescript" not "Use TypeScript") +- Check it's under 50 characters +- Check if filename `NNNN-{title}.md` already exists in `{adr_location}` (prevent duplicates) +- If validation fails, ask user to provide a corrected title + +## Common Generation Steps + +### Generate the ADR file + +1. Create the ADR file at `{adr_location}/NNNN-.md` using the template +2. Replace ALL template placeholders with actual content (see `guidelines.md` for template placeholder replacement rules) +3. Set today's date in YYYY-MM-DD format +4. Use comma-separated decider names as provided by user +5. Ensure "## Pros and Cons of the Options" section has subsections for each option with their specific pros/cons + +### Update the index + +1. Read `{adr_location}/README.md` +2. If README doesn't exist, create one using the structure from `references/README-example.md` +3. Find the "## Index" section +4. If Index section doesn't exist, add it at the end of the README (before any "Contributing" or "License" sections if they exist) +5. Generate one-line summary from the Decision Outcome section +6. Add entry format: `- [ADR-NNNN: Title](NNNN-title.md) - One-line summary` +7. Check for duplicate entries before adding +8. Write the updated README + +### Present the result + +Use the Read tool to show the user the full created ADR file content and ask if any changes are needed. diff --git a/posit-dev/adr/references/example-adr.md b/posit-dev/adr/references/example-adr.md new file mode 100644 index 0000000..6773249 --- /dev/null +++ b/posit-dev/adr/references/example-adr.md @@ -0,0 +1,102 @@ +# Use MADR Format for Architecture Decision Records + +* Status: accepted +* Deciders: Core Team, Technical Lead +* Date: 2024-01-15 + +Technical Story: As the project grows, we need a consistent way to document significant architectural decisions for future reference and to help onboard new contributors. + +## Context and Problem Statement + +The team needs a standardized format for documenting architectural decisions. Currently, important decisions are scattered across pull requests, GitHub issues, and meeting notes, making it difficult to understand the reasoning behind current architecture. How should we document architectural decisions in a way that's accessible, searchable, and maintainable? + +## Decision Drivers + +* Must be easy to write in plain text (developer-friendly) +* Should work well with version control (git-friendly) +* Must be searchable and browsable without special tools +* Should provide sufficient structure without being overly complex +* Should be well-adopted in the open-source community with good examples +* Need to capture alternatives considered, not just the final decision + +## Considered Options + +* MADR (Markdown Any Decision Record) +* Y-statements (minimal format) +* Plain markdown files with no template +* Michael Nygard's original ADR format + +## Decision Outcome + +Chosen option: "MADR (Markdown Any Decision Record)", because it provides comprehensive structure while remaining simple to use, has good tooling support, and is widely adopted in the open-source community. It strikes the best balance between completeness and ease of use. + +### Positive Consequences + +* Consistent structure across all ADRs makes them easy to read and compare +* Encourages thorough consideration of alternatives before deciding +* Well-documented format with many examples available +* Active community support and tooling +* Captures both the "what" and the "why" of decisions +* Optional sections allow flexibility for simple vs complex decisions + +### Negative Consequences + +* More verbose than minimal formats like Y-statements +* Requires discipline to fill out all relevant sections +* May seem like overhead for very small decisions +* Team needs to learn the format (though it's straightforward) + +## Pros and Cons of the Options + +### MADR (Markdown Any Decision Record) + +Full-featured ADR format with comprehensive sections for context, options, decision outcome, and consequences. + +* Good, because it provides comprehensive structure that covers all important aspects +* Good, because it's widely adopted in open-source projects (many examples available) +* Good, because it has good documentation and templates +* Good, because it encourages thorough analysis of alternatives +* Good, because optional sections allow adapting to decision complexity +* Bad, because it can be verbose for very simple decisions +* Bad, because it requires more time to write than minimal formats + +### Y-statements + +Minimal one-line format: "In context X, facing concern Y, we decided for option Z to achieve quality Q, accepting downside D" + +* Good, because it's very concise and forces focus on essentials +* Good, because it's extremely quick to write +* Good, because it captures the core decision in one sentence +* Bad, because it lacks detail for complex decisions +* Bad, because it doesn't capture full pros/cons of alternatives +* Bad, because it's hard to search and browse multiple decisions +* Bad, because it may omit important context + +### Plain markdown with no template + +Freeform markdown files without a prescribed structure or template. + +* Good, because it's completely flexible +* Good, because there's no learning curve +* Good, because writers can adapt to each decision's needs +* Bad, because consistency is difficult to maintain +* Bad, because important details might be accidentally omitted +* Bad, because new contributors don't know what to include +* Bad, because comparing decisions across time is harder + +### Michael Nygard's Original ADR Format + +The original ADR format with sections: Title, Status, Context, Decision, and Consequences. + +* Good, because it's the original and well-known format +* Good, because it's simpler than MADR (fewer sections) +* Good, because it captures the essential information +* Bad, because it doesn't explicitly capture alternatives considered +* Bad, because it lacks the detail needed for complex decisions +* Bad, because MADR is an evolution with more community adoption now + +## Links + +* [MADR Project](https://adr.github.io/madr/) +* [ADR GitHub Organization](https://adr.github.io/) +* [Original ADR article by Michael Nygard](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) diff --git a/posit-dev/adr/references/guidelines.md b/posit-dev/adr/references/guidelines.md new file mode 100644 index 0000000..ff8bcf4 --- /dev/null +++ b/posit-dev/adr/references/guidelines.md @@ -0,0 +1,147 @@ +# ADR Guidelines and Best Practices + +## File Structure + +ADRs are typically stored in a dedicated directory at the project root (commonly `adr/` but can be customized) with this structure: + +``` +{adr_location}/ +├── README.md # Index and documentation +├── _template.md # Template for new ADRs +├── 0001-title.md # Individual ADRs +├── 0002-title.md +└── ... +``` + +## Naming Convention + +ADRs follow the naming pattern: + +``` +NNNN-.md +``` + +Where: +- `NNNN` is a 4-digit sequence number (0001, 0002, etc.) +- `` is a short, descriptive title + +Examples: +- `0001-use-adr-system.md` +- `0002-adopt-express-mode.md` +- `0003-vendor-bslib-assets.md` + +## ADR Status Lifecycle + +``` +proposed → accepted → [deprecated | superseded] + ↓ + rejected +``` + +- **proposed**: Initial state, under review +- **accepted**: Decision approved and in effect +- **rejected**: Decision not approved +- **deprecated**: Decision no longer relevant +- **superseded**: Replaced by a newer ADR (link to the new one) + +## When to Write an ADR + +Write an ADR when: + +- Adding a new major feature or component +- Changing existing architectural patterns +- Making technology or dependency choices +- Establishing new conventions or standards +- Deprecating or removing significant functionality + +You probably don't need an ADR for: + +- Bug fixes +- Minor refactoring +- Documentation updates +- Routine dependency updates + +## Index Management + +Always update `{adr_location}/README.md` when creating a new ADR. Add an entry under the Index section: + +```markdown +## Index + +- [ADR-0001: Use ADR System](0001-use-adr-system.md) - Adopt MADR format for documenting decisions +- [ADR-0002: Adopt Express Mode](0002-adopt-express-mode.md) - Simplify single-file Shiny apps +``` + +The format is: `- [ADR-NNNN: Title](NNNN-title.md) - One-line summary` + +## Template Placeholder Replacement + +When generating any ADR, replace ALL bracketed placeholders in the MADR template with actual content: + +**Header section:** +- `[short title of solved problem and solution]` → Actual ADR title +- `[proposed | rejected | ...]` → Actual status (proposed, accepted, rejected, deprecated, superseded) +- `[list everyone involved in the decision]` → Comma-separated list of decider names +- `[YYYY-MM-DD when the decision was last updated]` → Today's date or decision date +- `[description | ticket/issue URL]` → Technical story text or issue link + +**Body sections:** +- `[Describe the context...]` → Actual context description +- `[driver 1, e.g., a force, facing concern, …]` → Actual decision drivers +- `[option 1]`, `[option 2]`, etc. → Actual option names +- `[justification...]` → Actual justification for chosen option +- `[e.g., improvement of quality attribute...]` → Actual consequences +- `[example | description | pointer to more information | …]` → Actual option description +- `[argument a]`, `[argument b]`, etc. → Actual pros/cons + +**General rules:** +- Remove ALL square brackets +- Remove HTML comments like `` +- For optional sections with no content: use "N/A" or remove the section entirely +- Ensure the "## Pros and Cons of the Options" section has a `### [Option Name]` subsection for each alternative with its specific pros/cons listed as bullet points + +## Important Rules + +1. **ALWAYS read the project's ADR template** (`{adr_location}/_template.md`) if it exists before creating new ADRs +2. **ALWAYS update the index** in `{adr_location}/README.md` when creating new ADRs +3. **ALWAYS use kebab-case** for ADR filenames +4. **ALWAYS set today's date** in YYYY-MM-DD format +5. **ALWAYS replace template placeholders** with actual content (including removing brackets and HTML comments) +6. **NEVER skip the template structure** - all sections should be present even if brief +7. **ALWAYS link related issues/PRs** if they exist +8. **ALWAYS ask clarifying questions** if information is missing rather than guessing +9. **ALWAYS show the user the file content** using the Read tool before considering the ADR finalized + +## Error Handling and Edge Cases + +**No ADR directory exists or is empty:** +1. Ask user: "I don't see any existing ADRs in `adr/`. Is there a different location where ADRs are stored in this project, or should I initialize the ADR system in `adr/`?" +2. If user provides different location, use that location (`{adr_location}`) for all subsequent operations +3. If user wants initialization, request consent: "I'll create the directory, README.md, and _template.md. Proceed?" +4. If yes, create: + - Directory at specified location + - README.md using the structure from `references/README-example.md` + - _template.md copying content from `references/_template.md` + +**No template found at `{adr_location}/_template.md`:** +Use the MADR template from skill's `references/_template.md` as fallback. + +**README.md doesn't exist:** +Create one using the structure from `references/README-example.md`. + +**README.md exists but no Index section:** +Add "## Index" section at the end of the file (before any "Contributing" or "License" sections if they exist) with the new ADR entry. + +**Duplicate ADR number:** +Check if `NNNN-*.md` already exists. If yes, increment to next available number. Use glob pattern `[0-9][0-9][0-9][0-9]-*.md` to match only 4-digit numbered ADRs. + +**Title validation failures:** +- Not kebab-case: Suggest converting (e.g., "Use TypeScript" → "use-typescript") +- Too long (>50 chars): Ask user to shorten +- Already exists: Suggest alternative title + +**Not a git repository:** +Use current working directory as the base path for ADR location. + +**Unclear or missing information:** +Don't guess - always ask the user for clarification. It's better to have an incomplete ADR that's accurate than a complete one with assumptions. diff --git a/posit-dev/adr/references/interview-flow.md b/posit-dev/adr/references/interview-flow.md new file mode 100644 index 0000000..72220f3 --- /dev/null +++ b/posit-dev/adr/references/interview-flow.md @@ -0,0 +1,127 @@ +# Interview Flow for Past Decisions + +This document provides the detailed interview script for capturing past architectural decisions. + +## Phase 1: Set the Stage + +Start with: "I'll help you document a past architectural decision as an ADR. Let's start with the basics." + +**Question 1**: "What decision would you like to document? Give me a brief title or description." + +*Wait for response before continuing.* + +## Phase 2: Understand the Context + +**Question 2**: "When was this decision made? (Approximate date is fine)" + +**Question 3**: "Who was involved in making this decision?" + +**Question 4**: "What was the situation that led to needing this decision? What problem were you trying to solve?" + +*Summarize back*: "So if I understand correctly, [summary of context]. Is that right?" + +## Phase 3: Explore Alternatives and Their Trade-offs + +**Question 5**: "What options did you consider? Even briefly considered or rejected ideas count." + +*Wait for response listing options.* + +For each option mentioned, **immediately** ask: +- "Tell me about [option] - what were the pros?" +- "What were the cons or concerns about [option]?" +- *Summarize*: "So [option] was good for [pros] but had issues with [cons]. Is that right?" + +**Note:** Store each option with its associated pros/cons. In Phase 6, these will map to individual option blocks in the "## Pros and Cons of the Options" section. Each option gets its own subsection with its specific good/bad points. + +Then move to the next option. + +If they only mention one option: "Was there ever any discussion of doing it differently? Even approaches that were quickly dismissed?" + +**Handling many options:** If user lists 5+ options, continue through all of them systematically. +**Handling unclear memory:** If user can't remember details for some options, note what they do know and move on. +**Handling informal evaluation:** If options weren't formally evaluated, ask for their thoughts anyway and capture what they recall. + +## Phase 4: Understand the Decision Outcome + +**Question 6**: "Which option did you ultimately choose?" + +**Question 7**: "What were the main reasons for choosing this approach over the others?" + +**Question 8**: "What was the expected outcome or goal when you made this decision? What were you hoping to achieve?" + +## Phase 5: Capture Real-World Consequences + +Now that we've covered the options, their pros/cons, and the expected outcome, capture what actually happened: + +**Question 9**: "Now that this decision has been in place, what positive outcomes have you observed? How has it helped?" + +**Question 10**: "Have there been any negative consequences or challenges that resulted from this choice?" + +**Question 11**: "Were there any unexpected trade-offs or surprises - things you didn't anticipate when making the decision?" + +**Question 12**: "If you were making this decision again today, would you decide differently? Why or why not?" + +## Phase 6: Generate the ADR + +1. **Determine repository root and ADR location** + - Find git repo root or use working directory + - Check for ADR location, initialize if needed (with consent) + +2. **Read template** + - Read `{adr_location}/_template.md` or use `references/_template.md` + +3. **Determine and validate ADR number** + - List existing ADRs, validate next number, use `0001` if none exist + +4. **Synthesize interview answers into ADR format** + - Validate title (kebab-case, under 50 chars, no duplicate) + - Map interview responses to MADR sections: + - Phase 1 (decision title) + Phase 2 (problem context) → Context and Problem Statement + - Phase 2 (when decided) → Date + - Phase 2 (who decided) → Deciders (comma-separated) + - Phase 3 (options list) → Considered Options + - Phase 3 (pros/cons for each option) → Pros and Cons of the Options (create subsection for each option with its specific good/bad points) + - Phase 4 (chosen option, reasons, expected outcome) → Decision Outcome + - Phase 5 (positive outcomes observed) → Positive Consequences + - Phase 5 (negative outcomes, unexpected surprises) → Negative Consequences + - Replace all template placeholders with actual content + - For optional sections with no content: use "N/A" or remove if truly not applicable + - Remove HTML comments + +5. **Create and save the initial ADR file at `{adr_location}/NNNN-.md`** + +6. **Update index** + - Update or create `{adr_location}/README.md` with new entry at the end + - Entry format: `- [ADR-NNNN: Title](NNNN-title.md) - One-line summary` + +**Present the draft**: "Here's the ADR I've created based on our conversation. Please review it:" + +*Use the Read tool to show the full ADR file content* + +**Ask**: "Would you like me to make any changes before we finalize it?" + +## Phase 7: Finalize + +If user requests changes: +- Make the requested edits to the ADR file +- Save the updated version +- Show the updated content again if changes were substantial + +After any revisions (or if no changes requested): +- Ensure status is set to "accepted" (since this is a past decision already in effect) +- Confirm: "ADR created at `{adr_location}/NNNN-title.md`. The decision has been documented!" + +## Interview Tips + +- **Be patient**: Let the user think and recall details +- **Probe gently**: If answers are vague, ask follow-up questions +- **Validate understanding**: Summarize back to confirm accuracy +- **Accept uncertainty**: "I don't remember" is a valid answer +- **Note gaps**: If information is missing, note it in the ADR + +## Notes + +- Past decisions (documented via interview) should have status "accepted" since they're already in effect +- If a decision has since been reversed, set status to "superseded" or "deprecated" instead +- Link to any related PRs or issues if the user can recall them +- It's okay to have some sections less detailed for older decisions