---

name: secondbrain-adr description: | This skill should be used when the user asks to "create ADR", "document decision", "architecture decision", "add decision record", or mentions needing to record a technical decision with status tracking and category organization.

Create Architecture Decision Record

Create numbered ADRs with category-based organization and status workflow.

Prerequisites

Verify ADR entity is enabled in the secondbrain project:

1. Check for .claude/data/adrs/records.yaml
2. If not found, suggest running secondbrain-init with ADRs enabled

Workflow

Step 1: Gather Information

Collect from user or conversation context:

1. Category (determines number range):

   • infrastructure (0001-0999) — Architecture & infrastructure
   • feature (2000-2999) — Feature implementation
   • process (3000-3999) — Process & workflow

2. Title — Brief decision title (will be slugified for filename)

3. Context — What problem prompted this decision?

Step 2: Determine ADR Number

1. Load .claude/data/adrs/records.yaml
2. Find highest number in selected category range
3. Increment to get next number
4. Format: ADR-XXXX (zero-padded)

Number Ranges:

Copyinfrastructure: 0001 - 0999
feature:        2000 - 2999
process:        3000 - 3999

Step 3: Generate ADR Document

Use template from ${CLAUDE_PLUGIN_ROOT}/templates/entities/adr/TEMPLATE.md:

Filename: docs/adrs/ADR-XXXX-<title-slug>.md

Frontmatter:

Copy---
id: ADR-XXXX
status: draft
date_created: YYYY-MM-DD
date_updated: YYYY-MM-DD
author: <author>
category: <category>
---

Step 4: Update Records

Add entry to .claude/data/adrs/records.yaml:

Copy- number: XXXX
  title: "<title>"
  status: draft
  category: <category>
  created: YYYY-MM-DD
  file: docs/adrs/ADR-XXXX-<slug>.md
  author: <author>

Update last_number if this is the new highest.

Step 5: Update Sidebar

Add link to docs/.vitepress/config.ts under ADRs section.

Step 6: Confirm Creation

Copy## ADR Created

**ID:** ADR-0012
**Title:** Kubernetes Migration Strategy
**Category:** infrastructure
**Status:** draft
**File:** docs/adrs/ADR-0012-kubernetes-migration-strategy.md

### Next Steps
1. Edit the ADR to add context, options, and decision
2. Change status to 'proposed' when ready for review
3. Use /secondbrain-adr-status to update status

### Status Workflow
draft → proposed → admitted → applied → implemented → tested

Status Workflow

CopyDraft → Proposed → Admitted → Applied → Implemented → Tested
                          ↘ Rejected
                          ↘ Canceled

Additional Resources

• references/adr-template.md — Full ADR template