doc-adr
doc-adr captures a single architectural decision using the Context-Decision-Consequences pattern, positioned as Layer 5 in the specification-driven development flow. It records the rationale, chosen approach, evaluated alternatives, and accepted trade-offs for decisions that bridge container and component design.
doc-adr creates a single Architecture Decision Record documenting one choice with context, decision, and consequences.
AI-generated summary based on this skill's SKILL.md
Decision gist · record as of 2026-07-27
doc-adr creates a single Architecture Decision Record documenting one choice with context, decision, and consequences. doc-adr captures a single architectural decision using the Context-Decision-Consequences pattern, positioned as Layer 5 in the specification-driven development flow. It records the rationale, chosen approach, evaluated alternatives, and accepted trade-offs for decisions that bridge container and component design.
Use it when
- doc-adr's template covers context (background and constraints), decision (the chosen approach), consequences (outcomes and trade-offs).
- doc-adr prompts you to evaluate 2–3 alternatives alongside your chosen decision, capturing the pros, cons, and costs of each.
Verify before relying
Read SKILL.md below before installing (1 file). Open directory: indexed for reading, not audited.
Install
vladm3105/aidoc-flow-framework/doc-adr · 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 write an architecture decision record with doc-adr?
doc-adr guides you through creating a single architecture decision record using the Context-Decision-Consequences pattern. Start by documenting the context (the issue or constraint that prompted the decision), state your chosen decision clearly, then record the consequences (benefits and trade-offs). doc-adr structures this as a Layer 5 artifact that bridges BDD upstream to SPEC downstream, ensuring your architectural rationale is traceable and validated.
What should an ADR template for documenting architectural choices include?
doc-adr's template covers context (background and constraints), decision (the chosen approach), consequences (outcomes and trade-offs), and alternatives considered (2–3 options with pros, cons, and costs). The template also supports status lifecycle management (Proposed, Accepted, Deprecated, Superseded), upstream tags for traceability, and SPEC-Ready scoring to validate structure and quality gates before downstream use.
How does doc-adr document architectural decisions with alternatives and trade-offs?
doc-adr prompts you to evaluate 2–3 alternatives alongside your chosen decision, capturing the pros, cons, and costs of each. This evaluation becomes part of your record, making the architectural rationale explicit. By documenting trade-offs within consequences, doc-adr ensures stakeholders understand not just what was decided, but why other options were rejected and what was accepted in return.
What is doc-adr's role as a Layer 5 artifact in the SDD workflow?
doc-adr positions architecture decision records as Layer 5 in specification-driven development, bridging container and component design from BDD upstream to SPEC downstream. It validates ADR structure, upstream tags, and SPEC-Ready score to ensure traceability and quality. This placement lets architectural choices flow into detailed specifications while remaining linked to their original business drivers.
How does doc-adr manage ADR status and document lifecycle?
doc-adr supports status transitions from Proposed through Accepted to Deprecated or Superseded, letting you track when decisions were made, approved, and (if needed) replaced. This lifecycle management maintains a living record of architectural evolution, making it easy to see which decisions are current and which have been superseded, along with the rationale for any changes.
How do I validate an ADR created with doc-adr for quality and traceability?
doc-adr includes validation checks for ADR structure, upstream tags linking to BDD sources, and SPEC-Ready scoring to confirm the record meets quality gates. These validations ensure your decision record is complete, traceable back to its drivers, and ready for downstream consumption by specification and implementation teams.
SKILL.md
Rendered from the published skill. Quoted content, verbatim.
doc-adr
Purpose
Create an Architecture Decision Record (ADR) — Layer 5 of the SDD flow. An ADR records one architecture decision using the Context-Decision- Consequences pattern: why the decision is needed, what was chosen, the alternatives weighed, and the consequences accepted.
Layer: 5 — the decision bridge between Container (PRD) and Component (SPEC); ADR is not itself a C4 level. Upstream: EARS, BDD (per the necessary-upstream contract;
(truncated - see the full file via the links below)
File tree — 1 file
platforms/claude-code-plugin/skills/doc-adr/SKILL.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 single architecture decision record documenting one choice with context, decision, and consequences”
Give your agent the search over MCP, or paste the wish link into any chat. No install? Search from any chat →
Related skills
Automates the full ADR lifecycle from source documents (BRD, PRD, EARS, BDD) or free-text prompts through generation, validation, and iterative refinement. Detects whether an ADR exists, routes to generation or review-and-fix accordingly, and maintains the ADR index with passing scores. Supports single or batch processing with configurable quality thresholds and fix iteration limits.
doc-adr-fixer consumes audit reports and patches ADRs to resolve structural, referential, and content issues identified during quality review. It supports both team-mode validation (with multi-lens dispatch) and single-pass remediation, backing up originals and reverting regressions to prevent silent failures.
verify is a quality assurance auditor that gates feature work at three checkpoints: proposal readiness, dev doc completeness, and implementation verification. It searches for placeholder content, traceability gaps, missing acceptance criteria, and specification drift, then either passes the gate or blocks with exact findings. Designed to be adversarial—assuming work is incomplete until proven otherwise.
doc-bdd translates EARS requirements into Layer 4 acceptance scenarios using structured YAML (not Gherkin), each with Given-When-Then phases, element-level trace links to upstream EARS, and forward mapping to SPEC sections. Use this after EARS is complete and before ADR/SPEC authoring; for batch generation across multiple documents, the autopilot skill handles orchestration.
doc-tdd generates Layer 7 TDD artifacts that translate component contracts into concrete test cases with quality thresholds. It maps BDD scenarios to unit, integration, functional, and end-to-end tests, establishes coverage targets per type, and sequences the Red-Green-Refactor workflow before implementation begins.
doc-prd generates a Product Requirements Document as Layer 2 of the SDD workflow, converting business requirements into product capabilities, user personas, and measurable success criteria. It structures features and acceptance criteria at the container level, sitting between upstream BRD and downstream EARS artifacts.
More skills doc-validator (MIT) · project-adopt (MIT) · gate-check (MIT) · adr-drafting (MIT)