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
Install
vladm3105/aidoc-flow-framework/doc-adr · repository language: Python
git clone https://github.com/vladm3105/aidoc-flow-framework
cp -r aidoc-flow-framework/platforms/claude-code-plugin/skills/doc-adr ~/.claude/skills/doc-adrnpx skillfed install vladm3105/aidoc-flow-framework/doc-adrFrequently 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)
Read as markdown · JSON record · Browse the source repository
File tree — 1 file
platforms/claude-code-plugin/skills/doc-adr/SKILL.md