blueprint-derive-adr skill

---
model: opus
created: 2025-12-22
modified: 2026-02-06
reviewed: 2026-02-06
description: "Derive Architecture Decision Records from existing project structure, dependencies, and documentation"
allowed-tools: Read, Write, Glob, Grep, Bash, AskUserQuestion, Task
name: blueprint-derive-adr
---

Generate Architecture Decision Records (ADRs) for an existing project by analyzing code structure, dependencies, and documentation.

**Use Case**: Onboarding existing projects to Blueprint Development system, documenting implicit architecture decisions.

**Prerequisites**:
- Blueprint Development initialized (`docs/blueprint/` exists)
- Ideally PRD exists (run `/blueprint:derive-prd` first)

**Steps**:

## Phase 1: Discovery

### 1.1 Check Prerequisites
```bash
ls docs/blueprint/manifest.json
ls docs/prds/
```
If blueprint not initialized → suggest `/blueprint:init`
If no PRD → suggest `/blueprint:derive-prd` first (recommended, not required)

### 1.2 Create ADR Directory
```bash
mkdir -p docs/adrs
```

### 1.3 Analyze Project Structure
Explore the codebase to identify architectural patterns:

Use Explore agent:
```
<Task subagent_type="Explore" prompt="Analyze project architecture: directory structure, major components, frameworks used, design patterns">
```

Key areas to examine:
- **Directory structure**: How code is organized
- **Entry points**: Main files, index files
- **Configuration**: Config files, environment handling
- **Dependencies**: Package manifests, imports
- **Data layer**: Database, ORM, data models
- **API layer**: Routes, controllers, handlers
- **Testing**: Test structure and frameworks

## Phase 1.5: Conflict Analysis

Before generating new ADRs, check for existing decisions that may conflict or relate.

### 1.5.1 Check for Existing ADRs
```bash
ls docs/adrs/*.md 2>/dev/null | wc -l
```

If ADRs exist, analyze for potential conflicts with decisions about to be documented.

### 1.5.2 Determine Domain for New ADR

Map decision categories to domains:

| Decision Category | Domain Tag |
|------------------|------------|
| State Management | `state-management` |
| Database/ORM | `data-layer` |
| Framework Choice | `frontend-framework` |
| API Design | `api-design` |
| Authentication | `authentication` |
| Testing Strategy | `testing` |
| Styling Approach | `styling` |
| Build Tooling | `build-tooling` |
| Deployment | `deployment` |

### 1.5.3 Scan Existing ADRs in Same Domain

For each domain being documented:
```bash
grep -l "^domain: {domain}" docs/adrs/*.md
```

For each matching ADR with `status: Accepted`:
- Extract ADR number and title
- Extract decision outcome (chosen option)
- Calculate conflict score:
  - Same domain: +0.3
  - Both Accepted: +0.2
  - Opposite/different outcomes: +0.4
  - Age > 6 months: +0.1

### 1.5.4 Surface Potential Conflicts

If conflict score >= 0.7, prompt user:

```
question: "Found existing ADR in same domain: ADR-{XXXX} - {title}. How should the new decision relate?"
options:
  - label: "Supersede ADR-{XXXX}"
    description: "New ADR replaces the existing decision"
  - label: "Extend ADR-{XXXX}"
    description: "New ADR builds on the existing decision"
  - label: "Mark as related"
    description: "Decisions are connected but independent"
  - label: "No relationship"
    description: "Continue without linking"
```

Store the relationship choice for inclusion in the generated ADR frontmatter.

### 1.5.5 Handle Multiple Conflicts

If multiple potential conflicts in same domain:
- Present each for user decision
- Allow bulk "supersede all" option for replacing multiple outdated decisions

## Phase 2: Identify Architecture Decisions

### 2.1 Common Decision Categories

| Category | What to Look For | Example Decisions |
|----------|-----------------|-------------------|
| **Framework** | package.json, imports | React vs Vue, Express vs Fastify |
| **Language** | File extensions, tsconfig | TypeScript vs JavaScript |
| **State Management** | Store patterns, context | Redux vs Zustand vs Context |
| **Styling** | CSS files, styled imports | Tailwind vs CSS-in-JS vs SCSS |
| **Testing** | Test files, test config | Vitest vs Jest, Playwright vs Cypress |
| **Build** | Build config, bundlers | Vite vs Webpack, esbuild |
| **Database** | ORM config, migrations | PostgreSQL vs MongoDB, Prisma vs Drizzle |
| **API Style** | Route patterns, schemas | REST vs GraphQL, tRPC |
| **Deployment** | Docker, CI config | Container vs serverless |
| **Monorepo** | Workspace config | Turborepo vs Nx vs none |

### 2.2 Infer Decisions from Code
For each identified technology choice:
1. Note the current implementation
2. Consider common alternatives
3. Infer rationale from context/comments

### 2.3 Confirm with User
Use AskUserQuestion for key decisions:

```
question: "I found the project uses {technology}. Why was this chosen over alternatives?"
options:
  - "Performance requirements" → document performance rationale
  - "Team familiarity" → document team expertise factor
  - "Ecosystem/community" → document ecosystem benefits
  - "Specific feature needs" → ask for details
  - "Legacy/inherited decision" → document as inherited
  - "Other" → custom rationale
```

```
question: "Are there any architecture decisions you'd like to document that aren't visible in the code?"
options:
  - "Yes, let me describe" → capture additional decisions
  - "No, the inferred decisions are sufficient" → proceed
```

## Phase 3: ADR Generation

### 3.1 ADR Template (MADR format)
For each significant decision, create an ADR:

```markdown
---
id: ADR-{NNNN}                          # Derived from filename (0003-*.md → ADR-0003)
date: {YYYY-MM-DD}
status: Accepted | Superseded | Deprecated | Proposed
deciders: {who made the decision}
domain: {domain-tag}                    # Optional: state-management, data-layer, etc.
supersedes: ADR-{XXXX}                  # Optional: if superseding another ADR
extends: ADR-{XXXX}                     # Optional: if extending another ADR
relates-to:                             # Cross-document references
  - PRD-{NNN}                           # Related PRDs
  - ADR-{YYYY}                          # Related ADRs
github-issues: []                       # Linked GitHub issues
name: blueprint-derive-adr
---

# ADR-{number}: {Title}

## Context

{Describe the issue motivating this decision}
{What is the problem we're trying to solve?}
{What constraints exist?}

## Decision Drivers

- {driver 1, e.g., "Performance under high load"}
- {driver 2, e.g., "Developer experience"}
- {driver 3, e.g., "Maintainability"}

## Considered Options

1. **{Option 1}** - {brief description}
2. **{Option 2}** - {brief description}
3. **{Option 3}** - {brief description}

## Decision Outcome

**Chosen option**: "{Option X}" because {justification}.

### Positive Consequences

- {positive outcome 1}
- {positive outcome 2}

### Negative Consequences

- {negative outcome / tradeoff 1}
- {negative outcome / tradeoff 2}

## Pros and Cons of Options

### {Option 1}

- ✅ {pro 1}
- ✅ {pro 2}
- ❌ {con 1}

### {Option 2}

- ✅ {pro 1}
- ❌ {con 1}
- ❌ {con 2}

## Links

- {Related ADRs}
- {External documentation}
- {Discussion threads}

---
*Generated from project analysis via /blueprint:derive-adr*
```

### 3.2 Standard ADRs to Generate

Generate ADRs for these common decisions (if applicable):

| ADR | When to Create |
|-----|----------------|
| `0001-project-language.md` | Language/runtime choice |
| `0002-framework-choice.md` | Main framework selection |
| `0003-testing-strategy.md` | Test framework and approach |
| `0004-styling-approach.md` | CSS/styling methodology |
| `0005-state-management.md` | State handling (if applicable) |
| `0006-database-choice.md` | Database and ORM (if applicable) |
| `0007-api-design.md` | API style and patterns |
| `0008-deployment-strategy.md` | Deployment approach |

### 3.3 Create ADR README

Write the ADR README template to `docs/adrs/README.md` using the template from `blueprint-plugin/templates/adr-readme.md`.

The README is self-documenting: it includes a programmatic `fd` + `awk` command that generates the ADR index on demand, eliminating static tables that drift out of sync.

**Customizations when writing**:
- If undocumented decisions were identified during Phase 2 analysis that the user chose not to create full ADRs for, add them to the **Proposed ADRs** section:
  ```markdown
  ## Proposed ADRs

  Decisions identified but not yet documented as full ADRs:

  - [ ] {Decision topic} — {brief context} (identified {YYYY-MM-DD})
  - [ ] {Decision topic} — {brief context} (identified {YYYY-MM-DD})
  ```
- Keep the programmatic listing command intact — it replaces the need for a static index

## Phase 4: Relationship Updates & Validation

### 4.0 Update Superseded ADRs (Bidirectional Consistency)

If any new ADR supersedes an existing ADR:

1. **Read the superseded ADR file**
2. **Update its frontmatter**:
   - Change `status: Accepted` to `status: Superseded`
   - Add `superseded_by: ADR-{new_number}`
3. **Update the Links section** (add if missing):
   ```markdown
   ## Links
   - Superseded by [ADR-{number}](./{filename}.md)
   ```

4. **Report the update**:
   ```
   Updated ADR-{old_number}:
   - Status: Accepted → Superseded
   - Added: superseded_by: ADR-{new_number}
   - Updated Links section
   ```

**Example**: If ADR-0012 supersedes ADR-0003:
- In ADR-0012: `supersedes: ADR-0003`
- In ADR-0003:
  - `status: Superseded`
  - `superseded_by: ADR-0012`
  - Links section references ADR-0012

### 4.1 Update Manifest

Update `docs/blueprint/manifest.json` ID registry for each ADR:

```json
{
  "id_registry": {
    "documents": {
      "ADR-0003": {
        "path": "docs/adrs/0003-database-choice.md",
        "title": "Database Choice",
        "status": "Accepted",
        "domain": "data-layer",
        "relates_to": ["PRD-001"],
        "github_issues": [],
        "created": "{date}"
      }
    }
  }
}
```

### 4.2 Present Summary
```
✅ ADRs Generated: {count} records

**Location**: `docs/adrs/`

**Decisions documented**:
- ADR-0001: {title} - {status} [{domain}]
- ADR-0002: {title} - {status} [{domain}]
...

**Relationships established**:
- ADR-{new} supersedes ADR-{old} (status updated)
- ADR-{new} extends ADR-{existing}
- ADR-{new} related to ADR-{other}

**ADRs updated** (bidirectional consistency):
- ADR-{old}: status → Superseded, superseded_by → ADR-{new}

**Sources analyzed**:
- {list of analyzed files/patterns}

**Confidence levels**:
- High confidence: {list - clear from code}
- Inferred: {list - reasonable assumptions}
- Needs review: {list - uncertain}

**Recommended next steps**:
1. Review generated ADRs for accuracy
2. Add rationale where marked as "inferred"
3. Run `/blueprint:derive-adr-validate` to check relationship consistency
4. Run `/blueprint:prp-create` for feature implementation
5. Run `/blueprint:generate-skills` for project skills
```

### 4.2 Suggest Next Steps
- If PRD missing → suggest `/blueprint:derive-prd`
- If ready for implementation → suggest `/blueprint:prp-create`
- If architecture evolving → explain how to add new ADRs

## Phase 5: Update Manifest

Update `docs/blueprint/manifest.json`:
- Add `has_adrs: true` to structure
- Add ADRs to `generated_artifacts`
- Update `updated_at` timestamp

**Tips**:
- Focus on decisions with real alternatives (not obvious choices)
- Document inherited/legacy decisions as such
- Mark uncertain rationales for user review
- Keep ADRs concise - focus on "why", not implementation details
- Reference related ADRs when decisions are connected

### 4.3 Prompt for next action (use AskUserQuestion):

```
question: "ADRs generated. What would you like to do next?"
options:
  - label: "Create a PRP for feature work (Recommended)"
    description: "Start implementing a specific feature with /blueprint:prp-create"
  - label: "Generate project skills"
    description: "Create skills from PRDs for Claude context"
  - label: "Review and add rationale"
    description: "Edit ADRs marked as 'inferred' or 'needs rationale'"
  - label: "Document another architecture decision"
    description: "Manually add a new ADR"
  - label: "I'm done for now"
    description: "Exit - ADRs are saved"
```

**Based on selection:**
- "Create a PRP" → Run `/blueprint:prp-create` (ask for feature name)
- "Generate project skills" → Run `/blueprint:generate-skills`
- "Review and add rationale" → Show ADR files needing attention
- "Document another decision" → Restart Phase 2 for a specific decision
- "I'm done" → Exit

**Error Handling**:
- If minimal codebase → create fewer, broader ADRs
- If conflicting patterns → ask user which is intentional
- If rationale unclear → mark as "needs rationale" for user input