mcpField
S
spec-loop-write-adr

spec-loop-write-adr

github.com/dpolivaevDevelopment3550 installsUpdated 2w ago
Repository

About spec-loop-write-adr

spec-loop-write-adr is a skill for drafting and updating ADRs when requested by the user or routed through a Spec Loop workflow. It checks for unresolved decisions and organizes evidence into the required sections.

Key features

  1. 01Draft and update ADRs
  2. 02Check for important open decisions
  3. 03Classify inputs by section
  4. 04Record rationale in Analysis

Use cases

  1. 01Draft an ADR from a request
  2. 02Pause for clarification when new decisions emerge

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/dpolivaev/spec-loop --skill spec-loop-write-adr

After installing, type/spec-loop-write-adrin Claude Code to confirm it loaded.

Bundled filesadr-format.md

Details

From the project README

Use this skill for ADR writing only.

Before doing that work, read adr-format.md and apply it.

Read and apply project instructions such as AGENTS.md when present.

This skill writes ADRs. It does not decide by itself whether an ADR is required. ADR work starts when the User asks for it or when a Spec Loop workflow routes to it.

The ADR being drafted or updated is the governing artifact for this skill.

Use the same ADR format whether or not a task artifact also exists.

Mandatory clarification gate

Before drafting or revising the ADR as current truth, check whether any important open decision remains about the decision, its criteria, trade-offs, credible options, or the boundaries of the decision.

If yes, create only enough ADR structure to hold the topic and current evidence safely, then use spec-loop-clarify-task/SKILL.md to engage the User before continuing. Do not wait for the user to ask for clarification explicitly, and do not replace this handoff with unstructured criteria discussion or brainstorming.

Re-run this gate whenever later ADR drafting exposes a new important open decision.

Before writing or revising, classify each input item into its proper section:

  • Context = pre-decision facts that would still be true under another credible alternative, such as requirements, constraints, current-state findings, scope boundaries, and explicit deferrals;
  • Alternatives = credible competing options;
  • Analysis = the clarified reasoning, accepted criteria, trade-offs, option comparisons, and brief rationale for why the chosen option won; and
  • Decision = the chosen outcome as a TL;DR, including any explicit deferrals or major retained boundaries that are part of the outcome.

Treat Analysis as the ADR's authoritative decision-and-rationale ledger. Do not repeat an Analysis point elsewhere in decision-and-rationale form.

When a task artifact exists, use its Research, Analysis, and other ADR-relevant sections such as Constraints, Design, and, when relevant, Scenario as the primary ADR inputs. Otherwise use confirmed chat clarification and other current evidence.

Comments

Markdown supported