skills.rest
Zaba505
Zaba505COMMUNITY
Explore all skills by this author →
WebsiteGitHub

define-adr

Drafts a single capability-scoped Architecture Decision Record in MADR 4.0.0 format.

1|Updated Mar 7, 2023
Search Tags:#adr#infrastructure as code#technical requirements#hugo#architecture decision record#madr#decision documentation
One-click install
npx skills add https://github.com/Zaba505/infra --skill define-adr-zaba505
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: define-adr
Source: https://github.com/Zaba505/infra/tree/main/.claude/skills/define-adr
Command: npx skills add https://github.com/Zaba505/infra --skill define-adr-zaba505

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes assets (resource) components.

What problem does it solve? Writing Architecture Decision Records by hand often produces documents that record only the final choice, losing the alternatives considered, the trade-offs weighed, and the requirements that drove the decision. This Skill enforces a disciplined ADR authoring workflow so every decision is auditable and traceable to technical requirements. ## Core Features & Use Cases - Research-before-options discipline: Surfaces unknown facts (current-state, external behavior, cost, compatibility) before drafting options, refusing to invent factual claims. - TR-anchored option analysis: Requires at least two options, each with pros and cons phrased in terms of the specific TR-NN technical requirements the decision addresses. - Human-picks gate: Never sets status: accepted on its own; the human explicitly selects an option, and unreviewed tech-requirements files block drafting entirely. - Use Case: After plan-adrs enumerates decisions for a capability, ask to draft the ADR for tenant state storage; the Skill checks the review gate, surfaces research tasks, drafts MADR 4.0.0 options tied to TRs, and writes the file to docs/content/capabilities/{name}/adrs/ once you pick. ## Quick Start Ask the assistant to draft the ADR for a specific capability decision, for example: draft the ADR for tenant state storage for the self-hosted-application-platform capability.

Frequently Asked Questions about define-adr

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

FAQPage Schema
How do I write an Architecture Decision Record for a single decision?▼

Identify the decision and its issue, verify the capability's tech-requirements.md has a current reviewed_at date, then draft at least two options evaluated against the cited TR-NNs. The ADR is saved as MADR 4.0.0 markdown under the capability's adrs/ directory with status proposed until you pick an option.

What is the difference between plan-adrs and define-adr?▼

plan-adrs enumerates and plans the full list of ADRs a capability needs, while define-adr authors exactly one ADR for one decision. define-adr runs once per ADR-issue created by plan-adrs and should not be used to plan multiple ADRs.

Why does define-adr refuse to draft my ADR?▼

It refuses when tech-requirements.md is missing, when reviewed_at is null or older than the file's last modification, or when the decision is cross-capability. Unreviewed requirements make the ADR meaningless, and shared decisions belong in docs/content/r&d/adrs/ via a separate flow.

Can the AI pick the best ADR option for me?▼

No. The skill's discipline requires the human to make the final selection; it will mirror the options back and may state a preference framed in TR terms, but it never writes status: accepted until you explicitly choose an option.

Does define-adr support the humus framework in proposed options?▼

No. The repo's CLAUDE.md states humus is not used, so options must follow the house pattern of chi router, bedrock config-from-env, protobuf request/response, and pkg/errorpb errors. Departures require explicit ADR-level justification tied to a TR.

Related Skills

Explore More Software Engineering Skills→
JunnnnyWonJunnnnyWon

create-stories

Generates implementable game story files from parsed epic docs, GDD requirements, ADRs, and control manifest.

Community
Advanced
liminal-ailiminal-ai
3

ls-tech-design

Transform feature specifications into tech design documents with architecture and test mapping.

Official
Advanced
gabergergaberger
4

hex-adr-search

Search Architecture Decision Records by keyword, status, or date.

Community
Intermediate
baotoqbaotoq
98

architecture-decision-records

Capture and manage architectural decisions with standardized ADR templates.

Community
Intermediate