capability-record-decision

Records technical decisions as ADR or ADL files and updates adoption documentation.

Updated Mar 31, 2026
One-click install
npx skills add https://github.com/learnn-com/engineering-kb --skill capability-record-decision-learnn-com
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: capability-record-decision
Source: https://github.com/learnn-com/engineering-kb/tree/main/.skills/capability-record-decision
Command: npx skills add https://github.com/learnn-com/engineering-kb --skill capability-record-decision-learnn-com

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Teams often lose track of why technical choices were made, and their architecture documentation drifts out of sync with actual practice. This Skill records every technical decision in a structured, dated file and keeps the project's adoption files as the single source of truth for what the team currently uses. ## Core Features & Use Cases - Decision Classification: Routes each decision to an ADR (architectural) or ADL (non-architectural) file, enforcing that the two are mutually exclusive. - Adoption File Synchronization: Always updates tech-stack.md, architecture.md, way-of-working.md, or other adoption files so they reflect the current state of facts. - Update and Supersede Handling: Detects existing decisions on the same topic, supports update mode, and marks superseded decisions with cross-references. - Use Case: After choosing a date library for a project, invoke the skill with type non-architectural and topic date-library-choice to create a dated ADL entry and automatically record the library in tech-stack.md. ## Quick Start Record a non-architectural decision about our date library choice and update the adoption files accordingly.

Frequently Asked Questions about capability-record-decision

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I record an architectural decision in a project?▼

Invoke the skill with type architectural and a kebab-case topic name. It creates a dated ADR file under adoption/tech/adr following the ADR template, then updates the affected adoption files such as architecture.md.

What is the difference between an ADR and an ADL entry?▼

An ADR documents architectural decisions affecting system structure, patterns, or quality attributes, while an ADL entry records non-architectural decisions like library choices or tooling preferences. The two are mutually exclusive for any single decision.

How do I update an existing decision record?▼

The skill scans the ADR or ADL directories for files matching your topic. If one exists, it asks whether to update that file or create a new decision, and update mode reads and modifies the existing content.

Does recording a decision also update project documentation?▼

Yes, updating adoption files is mandatory for every decision. The skill identifies affected files such as tech-stack.md, architecture.md, or way-of-working.md and modifies only the relevant sections while preserving existing content.

What happens if the ADR or ADL template is missing?▼

The skill degrades gracefully by falling back to a minimal structure containing Status, Date, Context, Decision, Consequences, and Adoption Impact. It also creates missing adoption directories with a warning that the project appears new.