architecture-definition-record

What this skill does

# Architecture Definition Record Skill

## Purpose

This skill is the **single owner of all ADR write operations**. It creates, updates, and manages Architecture Decision Records (ADRs) — immutable documents that capture the context, rationale, and consequences of significant architectural choices.

**Other skills read `adr/*.md` directly** for context loading, compliance, review, and export. They must **delegate here** when they need to create or modify any ADR file.

---

## When to Invoke This Skill

- User asks to create a new ADR or document an architectural decision
- User asks to update an ADR's status (Accepted, Deprecated, Rejected)
- User asks to supersede an existing decision with a new one
- User asks to list, audit, or review the ADR inventory
- User says: "add an ADR for…", "document this decision as an ADR", "mark ADR-XXX as accepted"
- Another skill triggers ADR file generation (e.g., after ARCHITECTURE.md creation)
- Use `/skill architecture-definition-record`

**Do NOT invoke for:**
- Reading ADRs as editing context → read `adr/*.md` directly
- Exporting ADRs to Word → use `architecture-docs-export` skill
- Reviewing ADR quality → use `architecture-peer-review` skill
- Referencing ADRs in compliance → compliance agents read `adr/README.md` directly

---

## Files in This Skill

| File | Purpose |
|------|---------|
| `SKILL.md` | This file — entry point and all workflows |
| `ADR_GUIDE.md` | Comprehensive guide: template structure, best practices, status lifecycle, comparison table standards |
| `adr/ADR-000-template.md` | Canonical ADR template — 10 sections, usage guide, file naming convention |

---

## Canonical Template Rule (ALL Workflows)

Every ADR file written by this skill MUST use the full 10-section canonical template from:
```
[plugin_dir]/skills/architecture-definition-record/adr/ADR-000-template.md
```

**No workflow may write an ADR file without first loading this template.** If the template cannot be loaded, the workflow MUST abort with:
```
TEMPLATE LOAD FAILURE: Could not load ADR-000-template.md. ADR generation aborted.
```

This applies to Workflows 1, 2, and 4. There are no exceptions.

---

## Workflows

### Workflow 1 — Generate ADRs from ARCHITECTURE.md Section 12 Table

**Trigger**: Called by `architecture-docs` after ARCHITECTURE.md creation, after Section 12 ADR table updates, or by user explicitly.

**Objective**: Extract the ADR table from ARCHITECTURE.md and generate `adr/ADR-XXX-title.md` files.

#### Step 1.0: Present ADR Generation Prompt

After ARCHITECTURE.md is created, display:

```
✅ Architecture documentation created successfully!

═══════════════════════════════════════════════════════════
📋 Architecture Decision Records (ADRs) Setup
═══════════════════════════════════════════════════════════

Your ARCHITECTURE.md includes an ADR table. I can automatically generate
ADR files using the standard template.

Would you like me to generate the ADR files now?

1. [Yes - Generate ADRs] - Create all ADR files listed in the table
2. [Preview First]       - Show me which ADRs will be created
3. [No Thanks]           - I'll create them manually later
4. [Learn More]          - Tell me about ADRs and the template

Recommended: Option 1 (Generate ADRs) - Saves time and ensures consistency
```

**Wait for user response.**

#### Step 1.1: Handle User Selection

- **Option 1 (Yes)** → Step 1.2
- **Option 2 (Preview)** → Step 1.2, then show preview, re-prompt yes/no
- **Option 3 (No)** → Show skip message with manual instructions
- **Option 4 (Learn More)** → Show ADR overview from `ADR_GUIDE.md`, re-prompt

#### Step 1.2: Locate ADR Table

Read `ARCHITECTURE.md` in full and parse the ADR table:

```bash
grep -E "^\| \[ADR-" ARCHITECTURE.md
```

**If no ADR table found:**
```
⚠️  ADR table not found in ARCHITECTURE.md
Options:
1. [Add ADR Table]       - Add the ADR section to ARCHITECTURE.md
2. [Skip ADR Generation] - Continue without generating ADRs
3. [Manual Review]       - Let me check the navigation index first
```

#### Step 1.3: Extract ADR List

For each line matching `^\| \[ADR-`:
1. Extract ADR number (e.g., `001`)
2. Extract file path (e.g., `adr/ADR-001-name.md`)
3. Extract slug from file path (or generate from title)
4. Extract title, status, date, impact
5. Extract Scope if a Scope column is present (see scope handling below)

**Regex:**
```
^\| \[ADR-(\d{3})\]\(adr\/ADR-\d{3}(-[a-z0-9-]+)?\.md\) \| (.+?) \| (.+?) \| (.+?) \| (.+?) \|
```

**Validate**: Check for duplicate ADR numbers — warn and halt if found.

**Scope handling — two cases:**

**Case A — Section 12 table has an explicit `Scope` column:**

Extract the Scope value from each row (`Institutional` or `User`). Validate that:
- Institutional rows use numbers 001–100
- User rows use numbers 101+

If mismatched (e.g., a "User" row with number 042), warn before generating:
```
⚠️  ADR-042 is labeled "User" but uses an institutional number (001–100).
    Options:
      1. [Reclassify to Institutional] — keep number 042, set Scope=Institutional
      2. [Renumber]                    — assign next available User slot (ADR-{next_user})
      3. [Keep as-is]                  — not recommended (breaks scope partition)
```

**Case B — Section 12 table has no `Scope` column (legacy / existing projects):**

Infer scope from the ADR number range: 001–100 → Institutional, 101+ → User.

Before writing any files, present an inferred-scope confirmation:
```
═══════════════════════════════════════════════════════════
INFERRED SCOPES (no Scope column in ARCHITECTURE.md Section 12)
═══════════════════════════════════════════════════════════
  ADR-001  [Title]   → Institutional  (number in range 001–100)
  ADR-002  [Title]   → Institutional  (number in range 001–100)
  ADR-101  [Title]   → User           (number ≥ 101)
═══════════════════════════════════════════════════════════
Proceed with these inferred scopes?  [all / specify overrides (e.g. 001=User) / cancel]
```

User can override individual ADRs before generation proceeds.

**If empty table:**
```
ℹ️  ADR table is empty. This is normal for newly created ARCHITECTURE.md files.
Create ADRs as architectural decisions are made using Workflow 2 (Create Individual ADR).
```

#### Step 1.4: Load Template

Resolve plugin directory and load the canonical template:

```bash
PLUGIN_DIR=$(find "$HOME" -maxdepth 10 -type d -name "solutions-architect-skills" ! -path "*/node_modules/*" 2>/dev/null | head -1)
Read(file_path="$PLUGIN_DIR/skills/architecture-definition-record/adr/ADR-000-template.md")
```

Store template content in memory for reuse across all ADR files.

#### Step 1.5: Generate Each ADR File

> **CRITICAL**: Use the **full canonical template** (all 10 sections). Do NOT produce abbreviated stubs with empty body sections. Every section for which architecture documentation provides relevant context MUST be populated. Only Implementation Plan and Success Metrics may remain as optional stubs.

> **Institutional content discipline**: When generating any ADR with `Scope: Institutional` (numbers 001–100), apply the rules in `ADR_GUIDE.md § Institutional ADR Content Discipline` — no "Institutional Inheritance Note", no "Project Application" sections, no component/operator/budget/timeline specifics, no cross-refs to ADR-101+. If source material from `ARCHITECTURE.md` contains those specifics, generalize them in the institutional ADR (and optionally retain the specifics in a paired User/Project ADR).

For each ADR in the list:

**Generate file path:**
- Slug from table path if present, else generate from title (lowercase, hyphens, strip special chars, max 50 chars)
- Placeholder title `[Title]` → slug `untitled`

**Check for existing file (never auto-overwrite):**
```
⚠️  ADR file conflict: adr/ADR-001-old-title.md already exists
1. [Skip This ADR]   - Keep existing file
2. [Rename New ADR]  - Create as ADR-{next_available}
3. [Overwrite]       - Replace existing (destructive)
4. [Review Existing] - Show me