Skip to content
Skills Library
Programming · Writing

dev10x:adr

/dev10x:adr

Create Architecture Decision Records (ADRs) following project conventions. Extends the base scope skill with ADR-specific format, numbering, diagram generation, and decision documentation. TRIGGER when: documenting significant architectural decisions, design trade-offs, or technology choices that affect the codebase. DO NOT TRIGGER when: making code changes without architecture impact, or writing commit messages (use dev10x:git-commit).

Licence
MIT
Last repository change
12.10.2026

Assessment and security

90/ 100Class: good
Format15 / 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
3
Scripts
0
HTML comments
0
URLs in SKILL.md
2
Deprecation

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

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Create Architecture Decision Records (ADRs) following project conventions. Extends the base scope skill with ADR-specific format, numbering, diagram generation, and decision documentation. TRIGGER when: documenting significant architectural decisions, design trade-offs, or technology choices that affect the codebase. DO NOT TRIGGER when: making code changes without architecture impact, or writing commit messages (use dev10x:git-commit).

Original author description

Create Architecture Decision Records (ADRs) following project conventions. Extends the base scope skill with ADR-specific format, numbering, diagram generation, and decision documentation. TRIGGER when: documenting significant architectural decisions, design trade-offs, or technology choices that affect the codebase. DO NOT TRIGGER when: making code changes without architecture impact, or writing commit messages (use dev10x:git-commit).

How it works

  1. Orchestration
  2. Overview
  3. Prerequisites
  4. Workflow
  5. ADR Quality Checklist
  6. Integration with Other Skills
  7. References
Original SKILL.md headings · 218 lines, 776 words
SKILL.md preview
---
name: dev10x:adr
description: >
  Create Architecture Decision Records (ADRs) following project conventions.
  Extends the base scope skill with ADR-specific format, numbering, diagram
  generation, and decision documentation.
  TRIGGER when: documenting significant architectural decisions, design
  trade-offs, or technology choices that affect the codebase.
  DO NOT TRIGGER when: making code changes without architecture impact,
  or writing commit messages (use dev10x:git-commit).
user-invocable: true
invocation-name: dev10x:adr
allowed-tools:
  - Bash(mkdir -p:*)
  - Bash(java -jar:*)
  - Bash(ls:*)
  - Skill(dev10x:ticket-branch)
  - Skill(dev10x:git-commit)
  - Skill(dev10x:gh-pr-create)
  - Agent
  - WebFetch
  - Grep
  - Glob
  - Read
---

# ADR Create - Architecture Decision Record Skill

## Orchestration

This skill follows `references/task-orchestration.md` patterns.
Create a task at invocation, mark completed when done:

**REQUIRED: Create a task at invocation.** Execute at startup:

1. `TaskCreate(subject="Create Architecture Decision Record", activeForm="Creating ADR")`

Mark completed when done: `TaskUpdate(taskId, status="completed")`

## Overview

This skill creates Architecture Decision Records (ADRs) following
the project's established format. It extends the base `dev10x:scope`
skill with ADR-specific workflows.

**Use when:**
- Documenting significant architectural decisions
- Proposing new integration patterns
- Recording technology choices
- Documenting system boundaries and responsibilities

**Do NOT use when:**
- Simple bug fixes (no architectural impact)
- Minor refactoring within existing patterns
- Configuration changes

## Prerequisites

Before invoking this skill, gather:
1. **Problem context** - What situation needs a decision?
2. **External references** (optional) - Documentation, API docs
3. **Linear ticket** (optional) - Associated ticket for linking

## Workflow

### Phase 1: Discovery (Uses base scope skill)

Follow the base `dev10x:scope` skill for context gathering:

1. **Understand the problem space**
   - What are we trying to solve?
   - What constraints exist?

2. **Research external resources** (if any)
   - Fetch and analyze documentation
   - Extract key concepts and patterns

3. **Explore existing codebase**
   - Find related patterns
   - Identify reusable components
   - Note naming conventions

4. **Identify components**
   - What exists vs. what's needed
   - Dependencies between components

### Phase 2: ADR-Specific Design

#### 2.1 Determine ADR Number

```bash
ls docs/adr/*.md | grep -E '^docs/adr/[0-9]{4}-' | sort | tail -1
```

If last is 0009, next is 0010.

#### 2.2 Create ADR Structure

Use the template in `references/adr-template.md` for the full
structure. Key sections:

- **Context** — situation, current state, problems
- **Decision** — architecture, key flows, new components
- **Alternatives Considered** — pros/cons/verdict for each
- **Consequences** — what becomes easier, harder, risks
- **Implementation Plan** — phased steps with file paths
- **References** — external docs, internal links

Default status: **Accepted**. Use Proposed only when explicitly
requesting review before acceptance.

#### 2.3 Create Diagrams Directory

```bash
mkdir -p docs/adr/diagrams/{ADR_NUMBER}/
```

### Phase 3: Diagram Creation

Use PlantUML patterns from `references/plantuml-patterns.md`.

#### 3.1 Component Architecture Diagram

Shows system boundaries and component relationships.

#### 3.2 Sequence Diagrams

Shows flow of operations for key interactions.

#### 3.3 Generate PNG Files

```bash
cd docs/adr/diagrams/{ADR_NUMBER}/
for f in *.puml; do
  java -jar ~/.local/bin/plantuml.jar "$f"
done
```

### Phase 4: Apply Design Principles

**YAGNI (You Aren't Gonna Need It):**
- Don't design features that aren't needed yet
- Remove unused return values
- Prefer void methods over complex returns

**Follow Existing Patterns:**
- Find similar implementations in codebase
- Use same layering (Entry Point → Service → Client)
- Follow naming conventions

**Clean Architecture:**
- Keep external dependencies at edges
- Business logic independent of frameworks
- Clear component responsibilities

### Phase 5: User Review Loop

**Critical:** Present findings to user and incorporate corrections.

Common corrections include:
- Business context not visible in code
- Organizational preferences
- Future plans affecting design
- YAGNI simplifications

**Iterate until user approves the architecture.**

### Phase 6: Finalize and Commit

#### 6.1 Create Branch

Use `dev10x:ticket-branch` skill if a ticket exists, or
`dev10x:git-worktree` for isolated workspace.

#### 6.2 Commit ADR

Use the `dev10x:git-commit` skill to commit:
- Stage `docs/adr/` directory
- Gitmoji: 📝
- Title: outcome-focused (e.g., "Document payment routing
  architecture")

#### 6.3 Create PR

Use `dev10x:gh-pr-create` skill for PR creation.

## ADR Quality Checklist

Before finalizing, verify:

### Content
- [ ] Context clearly explains the problem
- [ ] Decision is explicit and actionable
- [ ] Alternatives genuinely considered
- [ ] Consequences are honest (both easier and harder)
- [ ] Risks have mitigations

### Architecture
- [ ] Follows existing codebase patterns
- [ ] YAGNI applied
- [ ] Clean Architecture respected
- [ ] Component responsibilities clear

### Diagrams
- [ ] Component architecture shows system boundaries
- [ ] Sequence diagrams show key flows
- [ ] PNGs generated and referenced in ADR

### Implementation
- [ ] Steps ordered logically
- [ ] File paths specified
- [ ] Pattern references included
- [ ] Phases make sense

### Review
- [ ] User feedback incorporated
- [ ] Business context accurate
- [ ] Ready for implementation

## Integration with Other Skills

```
dev10x:adr
├── Extends: dev10x:scope (base scoping workflow)
├── May use: dev10x:work-on (if ticket exists)
├── Uses: dev10x:gh-pr-create (for PR creation)
└── Uses: dev10x:git-commit (for commit formatting)
```

## References

### ADR Format
- [Michael Nygard's ADR article](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions)
- [adr-tools](https://github.com/npryce/adr-tools)

### Project ADR Location
- ADRs: `docs/adr/NNNN-title.md`
- Diagrams: `docs/adr/diagrams/NNNN/`

### PlantUML
- Generate: `java -jar ~/.local/bin/plantuml.jar diagram.puml`
- Themes: `!theme plain` for clean diagrams
Files in this package (3)
  • SKILL.md 6 KB
  • references/adr-template.md 2 KB
  • references/plantuml-patterns.md 5 KB

Versions

The database has no other skills named dev10x:adr.

Database snapshot: 13.11.2026 · package version 0a029a5efd16 (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

  • 100architecture-decision-records
    Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation. Use when documenting significant technical decisions, reviewing past architectural choices, or establishing decision processes.
  • 84adr
    Create and manage Architecture Decision Records (ADRs). Use when someone asks to create an ADR, record an architecture decision, scaffold ADR support, or when a significant architectural decision surfaces during conversation.
  • 100arc42-chapter-09-architecture-decisions
    Guide for creating Architecture Decision Records (ADRs) following arc42 Chapter 9. Use when documenting architecture decisions, writing ADRs, justifying technical choices, or explaining consequences of architectural decisions. Triggers on requests involving "ADR", "architecture…
  • 95adr
    [UDS] Create, manage, and track Architecture Decision Records (ADR). Use when: architecture decisions, technology choices, design trade-offs, pattern selection. Not for: decisions that do not change architecture — record them in the spec or commit; ideas not yet formed enough to…
  • 100architecture-decision-records
    Write and maintain Architecture Decision Records (ADRs) following best practices for technical decision documentation. Use when documenting significant technical decisions, reviewing past architect...
  • 95adr
    Create or review Architecture Decision Records. Use for ADRs, architecture decisions, durable trade-offs, new dependencies, contracts, or patterns.

Feedback and reports

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