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:

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

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

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