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

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

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

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:

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:

---
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:

  ## 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):

   ## 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:

{
  "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