adr-drafting
ADR Drafting helps teams document significant architectural decisions by creating new Architecture Decision Record files with a standard structure. It inspects your repository for existing ADR conventions, then drafts a new record with Title, Status, Context, Decision, and Consequences sections—defaulting to `docs/architecture/adr` when no convention exists.
ADR Drafting creates new Architecture Decision Record documents to document architectural choices with consistent templates and repository-aware naming.
AI-generated summary based on this skill's SKILL.md
Decision gist · record as of 2026-06-22
ADR Drafting creates new Architecture Decision Record documents to document architectural choices with consistent templates and repository-aware naming. ADR Drafting helps teams document significant architectural decisions by creating new Architecture Decision Record files with a standard structure. It inspects your repository for existing ADR conventions, then drafts a new record with Title, Status, Context, Decision, and Consequences sections—defaulting to `docs/architecture/adr` when no convention exists.
Use it when
- ADR Drafting structures each Architecture Decision Record with five key sections: Title (the decision name).
- Yes, ADR Drafting can generate an ADR template tailored to your needs, including database migration decisions.
Verify before relying
Read SKILL.md below before installing (3 files). Open directory: indexed for reading, not audited.
Install
giuseppe-trisciuoglio/developer-kit/adr-drafting · repository language: Python
Open directory. Skills are indexed for reading, not audited. Review a skill's body before installing it.
Frequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How do I document an architectural choice with adr-drafting?
ADR Drafting helps you create a new Architecture Decision Record by generating a structured file with standard sections. The skill inspects your repository for existing ADR conventions, then drafts a record with Title, Status, Context, Decision, and Consequences sections. If no convention exists, it defaults to storing the ADR in `docs/architecture/adr`.
What sections does adr-drafting include in a new ADR?
ADR Drafting structures each Architecture Decision Record with five key sections: Title (the decision name), Status (such as Proposed or Accepted), Context (background and problem statement), Decision (the chosen solution), and Consequences (trade-offs and impacts). This standard format ensures consistent documentation across your team's architectural decisions.
Can adr-drafting generate ADR template for database migration?
Yes, ADR Drafting can generate an ADR template tailored to your needs, including database migration decisions. It creates a properly named and located file following your repository's conventions, with all standard sections ready for you to fill in the specific context, rationale, and consequences of your database choice.
How does adr-drafting preserve architectural decisions for team knowledge?
ADR Drafting creates markdown files that document your technical rationale and trade-offs, preserving architectural decision history in a structured, searchable format within your repository. This enables team members to understand why past decisions were made and reference them when evaluating future architectural changes.
What naming convention does adr-drafting use for new records?
ADR Drafting follows your repository's existing ADR naming conventions when detected. If no convention exists, it defaults to sequential numbering (like ADR 0001) and stores files in `docs/architecture/adr`. The skill generates properly formatted filenames that integrate seamlessly with your project's documentation structure.
Does adr-drafting help document why we chose our tech stack?
Yes, ADR Drafting is designed to document technical decisions like technology stack choices. It helps you capture the Context (why the decision was needed), Decision (which tech stack was chosen), and Consequences (benefits and trade-offs), creating a permanent record that explains your architectural choices to current and future team members.
SKILL.md
Rendered from the published skill. Quoted content, verbatim.
ADR Drafting
Creates new Architecture Decision Record (ADR) documents for major architectural choices so teams can keep a clear history of why important technical decisions were made.
Overview
This skill helps create a new ADR from discovery to final markdown file. It confirms the decision details, inspects the repository for any existing ADR conventions, and drafts a new ADR with the standard sections Title, Status, Context, Decision, and Consequences.
When the repository does not already have an ADR convention, default to storing ADRs in docs/architecture/adr and use a zero-padded filename such as 0001-use-postgresql-for-primary-database.md.
See references/template.md for the default ADR template and references/examples.md for example ADRs
(truncated - see the full file via the links below)
File tree — 3 files
plugins/developer-kit-core/skills/adr-drafting/SKILL.md
plugins/developer-kit-core/skills/adr-drafting/references/examples.md
plugins/developer-kit-core/skills/adr-drafting/references/template.md
Let your AI agent find skills like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 56,283 agent skills by what they can do, searchable in plain language.
wish › “Create a new Architecture Decision Record to document an architectural choice”
Give your agent the search over MCP, or paste the wish link into any chat. No install? Search from any chat →
Related skills
This skill captures architectural decisions made during coding sessions as structured ADR documents that live alongside your codebase. It detects decision moments, gathers context and alternatives, and maintains a searchable log so future developers understand the reasoning behind your architecture.
Guides you through seven-phase ADR drafting via focused dialogue, asking one question per turn and pressure-testing your reasoning before self-critique. Enforces specificity on components, deciders, and architectural characteristics, then routes to discovery if foundations are shallow.
adr-backfill lets you record decisions that shipped long ago but were never written up as ADRs—typically surfaced by doc audits or code archaeology. It enforces stricter honesty than forward drafting by requiring a visible backfill marker so future readers know the record was reconstructed, not contemporaneous. The skill demands two independent evidence sources and refuses to draft when confidence in the reasoning is too low.
This skill walks you through the complete ADR lifecycle—from evaluating whether a decision is ready to record, through structured creation using the MADR template, to quality checks and ongoing log management. It grounds decisions in proven frameworks like START (readiness criteria) and ECADR (completion criteria), helping teams capture architectural rationale rather than just outcomes.
ADR Skill helps teams document architecture decisions as executable specifications for coding agents. It guides you through a four-phase workflow—scanning existing decisions, capturing intent through structured questions, drafting the record with implementation details, and validating against an agent-readiness checklist. Built for codebases where decisions must be explicit, measurable, and actionable.
adr-critique systematically reviews existing or inherited ADRs to identify violations of shared rules, gaps in business-to-architecture reasoning, and conflicts with neighboring decisions or LikeC4 models. Each issue surfaces as a single flag requiring architect sign-off before moving to the next, ensuring quality without bulk rewrites.
More skills Create Adr (NOASSERTION) · adr-writer (MIT) · Architecture Decision Records (NOASSERTION) · doc-adr (MIT) · 030-architecture-adr-general (Apache-2.0) · Create Adr Spike (unlicensed) · doc-adr-fixer (MIT) · notaire (MIT)