the-own-lab/adr-writing
skills/adr-writing/SKILL.md
Author an Architecture Decision Record under docs/projects/<project>/adr/. Only when a decision has cross-feature, immutable, long-lived consequences.
testing
Updated Apr 22, 2026
$ install --global
skillsauthnpx skillsauth add the-own-lab/Claude-company-of-one adr-writingInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 22, 2026, 11:14 AM119.5s1 file scanned
SKILL.md
- name:
- adr-writing
- description:
- Author an Architecture Decision Record under docs/projects/<project>/adr/. Only when a decision has cross-feature, immutable, long-lived consequences.
adr-writing
Purpose
Capture a significant architectural decision as an immutable record. ADRs are distinct from spec files: specs describe what one feature delivers; ADRs describe a constraint future features will live under.
This skill is used only in /think docs-writing context, where direct writes to
DESIGN.md are the deliverable. /dev must not invoke this skill; mid-step /dev
skills read BRIEF.md only.
Inputs
BRIEF.md## Current Contractand clarified decision fromclarify.- Existing ADR index under
docs/projects/<project>/adr/.
Outputs
docs/projects/<project>/adr/NNN-<past-tense-title>.mdwhere NNN is zero-padded and strictly one greater than the current max.- Updated
BRIEF.md## Active Specs → ADRs referencedwith the new path.
Procedure
- Confirm the decision is ADR-worthy: reversing it in 6 months would cost more than writing it now. If not, use a short note in DESIGN.md instead.
- Compute next NNN by listing
docs/projects/<project>/adr/and incrementing. - Use the project's existing ADR style (inspect NNN-1 first). At minimum include: Status, Date, Context, Decision, Consequences (+/-), Alternatives Considered, Non-Goals.
- Mark Status as
Proposedon first write. Flip toAcceptedonly after user review. - Reference the ADR from DESIGN.md where it constrains implementation.
Failure modes
- Numbering collision (two ADRs picking the same NNN) → recompute immediately before write; never assume.
- Temptation to edit a past Accepted ADR → refuse. Add a new ADR that supersedes it,
or add a
## Follow-upamendment at the bottom of the existing one. ADRs are immutable. - Decision is actually feature-scoped → drop it into DESIGN.md Alternatives instead.
Does not do
- Does not modify Accepted ADRs in place.
- Does not write code or tests.
- Does not stand in for
spec-writing.
Related Skills
the-own-lab/write-brief
documentation
VerifiedTrustedCommunity
Update BRIEF.md sections during a command run. Any skill that produces a brief-persisted artifact calls this to write it back.
SKILL.mdUpdated Apr 22, 2026
the-own-lab/verify
development
VerifiedTrustedCommunity
Post-code check: run tests + confirm TODO acceptance items map to passing tests; applies a security lens but is not a separate scan.
SKILL.mdUpdated Apr 22, 2026
the-own-lab/update-docs
documentation
VerifiedTrustedCommunity
Command post-step: write CHANGELOG + TODO once per command run. One call, not per-skill doc writes.
SKILL.mdUpdated Apr 22, 2026
the-own-lab/spec-writing
content-media
VerifiedTrustedCommunity
Author REQUIREMENTS.md + DESIGN.md + TODO.md for a feature. The three files are one contract; they ship together.
SKILL.mdUpdated Apr 22, 2026