architectural-decision-record

Name: architectural-decision-record
Author: testdouble

122stars12forks

How to install architectural-decision-record?

testdouble/han/architectural-decision-record

$npx -y skills add testdouble/han --skill architectural-decision-record

Installs into the current project.

Summary

Create, extract, or convert an ADR (architectural decision record) using the ADR template. Use when creating new ADRs, extracting an ADR from existing documentation, converting a document into an ADR, recording an architecture or design decision, or updating the status of an exis

Files · 1

View on GitHub

SKILL.md

1	# Create ADR
2
3	## Operating Principles
4
5	- YAGNI applies to ADRs themselves. Apply the evidence-based YAGNI rule from [../../references/yagni-rule.md](../../references/yagni-rule.md). An ADR is worth recording only when there is a concrete forcing function today — a real decision the team is actively making, an existing code path or architectural choice that will be locked in by this record, an applicable regulation, a customer commitment, or a documented incident that drove the choice. ADRs about decisions that don't have to be made yet, "for future flexibility", "best practice says we should pick X", or symmetry with other ADRs ("we have one for auth, so we should have one for billing") are YAGNI candidates and the ADR should not be written. When proposed, recommend deferral with the trigger that would justify writing the ADR (a real decision arising, a real incident, a real regulation taking effect). The user always wins; the rule's job is to make the cost of writing speculative architectural records visible — every ADR is a future-reader's load and a pattern future agents will treat as committed.
6	- The companion evidence rule applies to the ADR's supporting evidence. Apply the evidence rule from [../../references/evidence-rule.md](../../references/evidence-rule.md) to the citations that justify the ADR's decision and rejected alternatives. Name the trust class of each citation (codebase, web, provided); mark single-source web claims that drive the chosen option; and when no evidence at any tier supports a claimed trade-off, label it rather than presenting it as a weak preference.
7	- The readability rule shapes the ADR's prose. Load and apply the readability standard from [../../references/readability-rule.md](../../references/readability-rule.md) as you write the ADR. Hold its default audience frame: a capable reader who did not make this decision and lacks your context. The frame governs how each section reads, never whether a required technical fact appears.
8
9	## Project Context
10
11	- CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f`
12	- project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f`
13
14	## Step 1: Determine Mode
15
16	Determine which mode to operate in based on the user's request:
17
18	\| Mode \| When \| Initial Status \| Then \|
19	\|------\|------\|----------------\|------\|
20	\| Creating new \| Building an ADR from scratch for a new or recent decision \| `proposed` \| → Step 2 \|
21	\| Converting existing \| User provides an existing document to convert into an ADR \| `accepted` \| → Step 2 \|
22	\| Updating existing \| Modifying an existing ADR (status change, superseding, adding notes) \| — \| Read the existing ADR, → Step 3 \|
23
24	## Step 2: Discover Project Structure
25
26	1. Retrieve project config: Resolve project config: read CLAUDE.md's `## Project Discovery` section for docs and ADR directories; fall back to project-discovery.md; fall back to Glob defaults (`docs/`, `docs/adr/`). Continue without any keys that remain unfound.
27
28	2. Determine the ADR directory: Use the ADR directory if found; otherwise use `{docs-dir}/adr/` if a docs directory was found; otherwise use `docs/adr/`. Run `mkdir -p` on the resolved directory to ensure it exists.
29
30	3. Enumerate existing ADRs: Use Glob to find existing `.md` files in the ADR directory.
31
32	4. Check existing ADR format: If existing ADRs were found, read one to understand the project's format. If it differs from [template.md](./references/template.md), ask the user whether to match the existing format or use this skill's template.
33
34	5. Discover the filename hierarchy taxonomy: ADRs are organized by a one- or two-level hierarchy encoded in the filename so related decisions sort together in a directory listing. Discover the taxonomy that applies to this project — never hardcode it.
35	- From existing filenames: If existing ADRs were enumerated, parse their filenames to extract the leading hierarchy segments already in use (e.g., `auth-session-storage.md` → top-level `auth`; `auth-tokens-rotation.md` → top-level `auth`, second-level `tokens`). Build a list of top-level prefixes and known second-level prefixes per top-level.
36	- From project context: Read CLAUDE.md and project-discovery.md (paths from project context above) to identify the project's languages, frameworks,

People who liked this also viewed

6 picks

Type

architectural-decision-record

122stars12forks

View on GitHub

How to install architectural-decision-record?

testdouble/han/architectural-decision-record

$npx -y skills add testdouble/han --skill architectural-decision-record

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Create ADR
2
3	## Operating Principles
4
5	- YAGNI applies to ADRs themselves. Apply the evidence-based YAGNI rule from [../../references/yagni-rule.md](../../references/yagni-rule.md). An ADR is worth recording only when there is a concrete forcing function today — a real decision the team is actively making, an existing code path or architectural choice that will be locked in by this record, an applicable regulation, a customer commitment, or a documented incident that drove the choice. ADRs about decisions that don't have to be made yet, "for future flexibility", "best practice says we should pick X", or symmetry with other ADRs ("we have one for auth, so we should have one for billing") are YAGNI candidates and the ADR should not be written. When proposed, recommend deferral with the trigger that would justify writing the ADR (a real decision arising, a real incident, a real regulation taking effect). The user always wins; the rule's job is to make the cost of writing speculative architectural records visible — every ADR is a future-reader's load and a pattern future agents will treat as committed.
6	- The companion evidence rule applies to the ADR's supporting evidence. Apply the evidence rule from [../../references/evidence-rule.md](../../references/evidence-rule.md) to the citations that justify the ADR's decision and rejected alternatives. Name the trust class of each citation (codebase, web, provided); mark single-source web claims that drive the chosen option; and when no evidence at any tier supports a claimed trade-off, label it rather than presenting it as a weak preference.
7	- The readability rule shapes the ADR's prose. Load and apply the readability standard from [../../references/readability-rule.md](../../references/readability-rule.md) as you write the ADR. Hold its default audience frame: a capable reader who did not make this decision and lacks your context. The frame governs how each section reads, never whether a required technical fact appears.
8
9	## Project Context
10
11	- CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f`
12	- project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f`
13
14	## Step 1: Determine Mode
15
16	Determine which mode to operate in based on the user's request:
17
18	\| Mode \| When \| Initial Status \| Then \|
19	\|------\|------\|----------------\|------\|
20	\| Creating new \| Building an ADR from scratch for a new or recent decision \| `proposed` \| → Step 2 \|
21	\| Converting existing \| User provides an existing document to convert into an ADR \| `accepted` \| → Step 2 \|
22	\| Updating existing \| Modifying an existing ADR (status change, superseding, adding notes) \| — \| Read the existing ADR, → Step 3 \|
23
24	## Step 2: Discover Project Structure
25
26	1. Retrieve project config: Resolve project config: read CLAUDE.md's `## Project Discovery` section for docs and ADR directories; fall back to project-discovery.md; fall back to Glob defaults (`docs/`, `docs/adr/`). Continue without any keys that remain unfound.
27
28	2. Determine the ADR directory: Use the ADR directory if found; otherwise use `{docs-dir}/adr/` if a docs directory was found; otherwise use `docs/adr/`. Run `mkdir -p` on the resolved directory to ensure it exists.
29
30	3. Enumerate existing ADRs: Use Glob to find existing `.md` files in the ADR directory.
31
32	4. Check existing ADR format: If existing ADRs were found, read one to understand the project's format. If it differs from [template.md](./references/template.md), ask the user whether to match the existing format or use this skill's template.
33
34	5. Discover the filename hierarchy taxonomy: ADRs are organized by a one- or two-level hierarchy encoded in the filename so related decisions sort together in a directory listing. Discover the taxonomy that applies to this project — never hardcode it.
35	- From existing filenames: If existing ADRs were enumerated, parse their filenames to extract the leading hierarchy segments already in use (e.g., `auth-session-storage.md` → top-level `auth`; `auth-tokens-rotation.md` → top-level `auth`, second-level `tokens`). Build a list of top-level prefixes and known second-level prefixes per top-level.
36	- From project context: Read CLAUDE.md and project-discovery.md (paths from project context above) to identify the project's languages, frameworks,

People who liked this also viewed

6 picks

Type