Skip to content
Skills Library
Programming · Writing

secondbrain-adr

/secondbrain-adr

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.

Repository
ai ↗
Licence
Unlicense
Last repository change
17.08.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 17.08.2026, without references to retired models or APIs.

Licence

Unlicense, otwarta.

What it does and when to use it

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.

Triggers from the description

create ADRdocument decisionarchitecture decisionadd decision record
Original author 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.

How it works

  1. Prerequisites
  2. Important Rules
  3. Workflow
  4. Status Workflow
  5. Additional Resources
Original SKILL.md headings · 127 lines, 440 words
SKILL.md preview
---
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/meta.yaml` (sharded) or `.claude/data/adrs/records.yaml` (legacy)
2. If not found, suggest running `secondbrain-init` with ADRs enabled

## Important Rules

- **Do NOT add ADRs to the left sidebar/navigation.** ADRs are listed automatically via the `EntityTable` component on `docs/adrs/index.md`, which reads from `.claude/data/adrs/` shard files. No sidebar modification is needed.

## 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/meta.yaml` (read `last_number` — tiny file, ~50 tokens)
2. Find highest number in selected category range
3. Increment to get next number
4. Format: `ADR-XXXX` (zero-padded)

**Number Ranges:**
```
infrastructure: 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:**
```yaml
---
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 the current month's shard `.claude/data/adrs/YYYY-MM.yaml`:

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

Update `last_number` in `.claude/data/adrs/meta.yaml` and ensure the current month is in the `shards` list.

### Step 5: Sidebar Note

**DO NOT manually add ADRs to VitePress sidebar.**

ADRs are automatically listed via the `EntityTable` component on `docs/adrs/index.md`, which reads from `.claude/data/adrs/` shard files. No sidebar modification needed.

### Step 6: Confirm Creation

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

```
Draft → Proposed → Admitted → Applied → Implemented → Tested
                          ↘ Rejected
                          ↘ Canceled
```

| Status | Description |
|--------|-------------|
| draft | Initial creation, under development |
| proposed | Ready for review |
| admitted | Approved, pending implementation |
| applied | Implementation started |
| implemented | Implementation complete |
| tested | Verified in production |
| rejected | Not approved |
| canceled | Abandoned |

## Additional Resources

- **`references/adr-template.md`** — Full ADR template
Files in this package (2)
  • SKILL.md 4 KB
  • references/adr-template.md 3 KB

Versions

The database has no other skills named secondbrain-adr.

Database snapshot: 13.11.2026 · package version e74256c6e281 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100adr-writer
    Write an Architecture Decision Record (ADR) as a Markdown file. Use when the user asks to create, draft, document or record an architecture/technical decision, or mentions "ADR", "decision record" or "registro de decisión de arquitectura".
  • 100adr-writer
    Write or supersede an architecture decision record (ADR). Use to record a hard-to-reverse decision.
  • 90create-adr
    Write a new Architecture Decision Record under docs/adr/ in this repo's format (Status, Date, Deciders, Context, Decision, Consequences). Use when the user asks to write an ADR, record an architecture decision, or document why something was done. Numbers it after the highest…
  • 90create-adr
    Write a new Architecture Decision Record under docs/adr/ in this repo's format (Status, Date, Deciders, Context, Decision, Consequences). Use when the user asks to write an ADR, record an architecture decision, or document why something was done. Numbers it after the highest…
  • 100adr
    Writes or reviews an Architecture Decision Record (context, drivers, options, decision, consequences) stored per service repo. Use for \"write an ADR\", \"document this decision\", or recording why an approach was chosen.
  • 80decision-record
    Writes an architecture decision record (ADR). Use when the user says "record this decision", "write an ADR" or "we decided X, capture it".

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.