{"slug":"architectural-decision-record","title":"architectural-decision-record","summary":"Create, extract, or convert an ADR (architectural decision record) using the ADR template. Use when creating new ADRs, extracting an ADR from existing documentation, converting a document into an ADR, recording an architecture or design decision, or updating the status of an exis","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-10-15T13:11:54.778516Z","repo":{"url":"https://github.com/testdouble/han","stars":303,"forks":24,"license":"MIT","updatedAt":"2026-10-14T20:22:28Z"},"bodyHtml":"
\n

name: architectural-decision-record\ndescription: >\nCreate, extract, or convert an ADR (architectural decision record) using the ADR template. Use when creating new ADRs,\nextracting an ADR from existing documentation, converting a document into an ADR, recording an architecture or design\ndecision, or updating the status of an existing ADR. Does not create or update enforceable coding standards or\nconventions — use coding-standard for that. Does not write feature or system documentation — use project-documentation\ninstead.\nargument-hint: \"[topic-or-title or document-path]\"\nallowed-tools:\nRead, Write, Edit, Glob, Grep, Agent, Bash(mkdir *), Bash(find *),\nBash(bash \"$/scripts/han-config-dir.sh\")

\n

Create ADR

\n

Operating Principles

\n\n

Project Context

\n\n

As your first action, use the Read tool on .han/config.md inside the personal config directory path above. A read\nthat returns no file is no personal configuration: continue silently. When that file or the project .han/config.md\nprobe supplies content, apply it per config-rule.md, which governs precedence\nbetween the two files, relative-path resolution, and what to do with a file that reads but cannot be used.

\n

Step 1: Determine Mode

\n

Determine which mode to operate in based on the user's request:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
ModeWhenInitial StatusThen
Creating newBuilding an ADR from scratch for a new or recent decisionproposed→ Step 2
Converting existingUser provides an existing document to convert into an ADRaccepted→ Step 2
Updating existingModifying an existing ADR (status change, superseding, adding notes)—Read the existing ADR, → Step 3
\n

Step 2: Discover Project Structure

\n
    \n

  1. Retrieve project config: Resolve project config: read CLAUDE.md's ## Project Discovery section for docs and ADR\ndirectories; fall back to project-discovery.md; fall back to Glob defaults (docs/, docs/adr/). Continue without\nany keys that remain unfound.

    \n
    2. \n

  2. Determine the ADR directory: Use the ADR directory if found; otherwise use {docs-dir}/adr/ if a docs directory\nwas found; otherwise use docs/adr/. Run mkdir -p on the resolved directory to ensure it exists.

    \n
    3. \n

  3. Enumerate existing ADRs: Use Glob to find existing .md files in the ADR directory.

    \n
    4. \n

  4. Check existing ADR format: If existing ADRs were found, read one to understand the project's format. If it\ndiffers from template.md, ask the user whether to match the existing format or use this\nskill's template.

    \n
    5. \n

  5. Discover the filename hierarchy taxonomy: ADRs are organized by a one- or two-level hierarchy encoded in the\nfilename so related decisions sort together in a directory listing. Discover the taxonomy that applies to this\nproject — never hardcode it.

    \n\n
    6. \n
\n

Step 3: Gather Context

\n
    \n
  1. From the arguments and conversation, determine:\n\n
    2. \n
  2. If any of these are unclear or missing, use AskUserQuestion to clarify before writing. If the forcing function is\nthe unclear one, surface that explicitly — \"I don't see a current trigger forcing this decision; recommend deferring\nthe ADR until . Override?\"
    3. \n
\n

Explore the Codebase

\n

Skip agent exploration if the user has already provided full context (converting or updating). When creating a new ADR\nwith sparse context, launch 1-2 han-core:codebase-explorer agents to discover evidence. Use 1 agent for narrow\ndecisions, 2 when the decision crosses multiple system areas. Explorer 1 focuses on code affected by the decision topic\n(current patterns, entry points, core logic). Explorer 2 focuses on existing ADRs, coding standards, and project docs\n(starting from the docs directory found in Step 2).

\n

Compile Evidence

\n

After agents complete (or if skipped), merge findings with user-provided context. Agent discovery items map to Context\n(current state of the codebase), Decision (why the chosen option fits), and Notes (key files table, cross-references).\nMerge duplicates and resolve conflicts between agents.

\n

Dispatch Architectural Review

\n

Skip this sub-step in update mode when only status is changing. Otherwise, launch review agents in parallel against\nthe compiled evidence, the proposed decision, and the considered alternatives. Pass each agent the topic, the proposed\ndecision, the alternatives, and the evidence compiled above.

\n
    \n

  1. Launch architect agent — use han-core:software-architect when the decision is scoped to a single codebase or\nbounded context (module boundaries, class and interface design, abstraction points, refactoring paths). Use\nhan-core:system-architect when the decision crosses service or bounded-context seams (integration patterns, data\nownership across services, failure-domain topology, context-map relationships). If uncertain, prefer\nhan-core:system-architect. Prompt: \"Review the proposed decision against the compiled evidence. For the chosen\noption, identify structural or topological risks that the ADR's Consequences section should name. For each rejected\nalternative, identify the strongest case for it that the ADR's Decision section needs to rebut or concede. Return\nfindings keyed to the ADR's Decision, Decision Drivers, and Consequences sections.\"

    \n
    2. \n

  2. Launch han-core:risk-analyst agent — prompt: \"Assess the risk of adopting the chosen option versus staying with\nthe current approach or adopting each rejected alternative. Score each on likelihood, severity, blast radius, and\nreversibility. Return findings keyed to the ADR's Consequences section, and flag any dimension where a rejected\nalternative scores better than the chosen option — the ADR needs to explain why.\"

    \n
    3. \n

  3. Launch han-core:junior-developer agent in artifact-review mode — prompt: \"Read the proposed Context, Decision,\nDecision Drivers, and Considered Options as a generalist encountering this decision for the first time. Surface:\nunexplained jargon, assumptions baked into the Decision Drivers without evidence, alternatives dismissed without a\nreason a generalist would accept, and places where the ADR relies on context a future reader will not have. Return a\nshort list of clarifying questions and must-answer gaps.\"

    \n
    4. \n
\n

Merge the three agents' findings into the Decision, Decision Drivers, and Consequences sections before writing. Where an\nagent raises a must-answer gap that requires user judgment, surface it with a recommended resolution rather than\nresolving silently.

\n

Step 4: Write the ADR

\n
    \n

  1. Convert source document (if converting): Read the source document and map sections to ADR sections using the\nmapping at conversion-mapping.md.

    \n
    2. \n

  2. Copy the template from template.md

    \n
    3. \n

  3. File name and location: {top-level}[-{second-level}]-{kebab-case-title}.md — a one- or two-level hierarchy\nprefix followed by the decision's specific title. The hierarchy must come from the taxonomy discovered in Step 2.6,\nnever invented or hardcoded.

    \n\n
    4. \n

  4. Fill in metadata: Status per Step 1 mode (proposed for new, accepted for converted; use deprecated or\nsuperseded when updating). Date Created / Last Updated: current date and time.

    \n
    5. \n

  5. Fill each required section following the template's HTML comments for guidance. Readability: invoke\nhan-communication:readability-guidance to surface the shared readability standard into your context, then write the\nprose in each section against it — lead with the main point, give each paragraph one idea carried by its first\nsentence, number sequential steps and bullet non-sequential items, and disclose detail in layers. Keep the template's\nprescribed section structure (Context, Decision Drivers, Considered Options, Decision, Consequences, Notes); the rule\ngoverns the prose within them, and its descriptive-heading rule applies to any sub-headings you add, not the\nprescribed section names.

    \n
    6. \n

  6. Notes section must include:

    \n\n
    7. \n

  7. If updating an existing ADR: Update Status, Last Updated, and add notes about what changed. If superseding,\ncross-reference the new ADR and set the old ADR's status to superseded.

    \n
    8. \n

  8. Handle source document (conversions only): If the source document is fully subsumed, delete it and update\nreferences in CLAUDE.md, AGENTS.md, and other markdown files. If it retains useful content, add a link to the new ADR\nand remove migrated sections.

    \n
    9. \n
\n

Step 5: Integration

\n
    \n
  1. Add a See reference in the relevant section of any existing CLAUDE.md or AGENTS.md, following the pattern of\nexisting ADR references. Place it near the feature or component the ADR describes.
    2. \n
  2. Search for related documentation (other ADRs, coding standards, feature docs) and add cross-references in the new\nADR's Notes section.
    3. \n
  3. Add back-references from related docs where they add value.
    4. \n
  4. If converting (Step 4), confirm all old references to the source document are updated.
    5. \n
\n

Step 6: Verification

\n

Read back the ADR file and confirm:

\n
    \n
  1. All metadata fields are filled (no {placeholder} values remain) and template structure from\ntemplate.md was followed
    2. \n
  2. All required sections (Context, Decision Drivers, Considered Options, Decision, Consequences, Notes) have substantive\ncontent, and Notes includes a key files table with paths verified by Glob
    3. \n
  3. Cross-references in the ADR point to documents that exist
    4. \n
  4. Agent configuration file references (CLAUDE.md/AGENTS.md) correctly point to the new ADR
    5. \n
  5. If converting: source document was handled (deleted or updated with link)
    6. \n
  6. Fix any issues found
    7. \n
\n

Step 7: Readability Self-Check

\n

Run the standardized readability self-check (the shared standard is in your context from\nhan-communication:readability-guidance) over the ADR's prose regions only — never inside code fences, diagram bodies,\nor citation identifiers. This skill runs no rewrite pass, so this self-check is the fidelity guard on the output; the\nfidelity criterion is not optional. Confirm each criterion and fix any failure before presenting:

\n

Run the readability rule's standardized self-check, which is already in your context from the readability-guidance\ninvocation above. Correct every failure before presenting. Its fidelity criterion is not optional: the standard governs\nhow the content is said, and drops a required fact only when the reader asked for less and losing it would not change\nwhat they do next.

\n

The descriptive-heading criterion applies to sub-headings you added, not to the section names the ADR template\nprescribes.

\n","files":[{"path":"references/conversion-mapping.md","sizeBytes":756,"isText":true},{"path":"references/template.md","sizeBytes":1111,"isText":true},{"path":"SKILL.md","sizeBytes":16323,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-10-15T13:12:04.5858Z","sha256":"B9679065E3430EB6F0E5DCAAC07E89845CD60256CC5481440DA49A2FB37DD283","sizeBytes":7531},"review":null,"source":{"repositoryUrl":"https://github.com/testdouble/han","path":"han-documentation/skills/architectural-decision-record","license":"MIT","commit":"abba73a773528905a8f3d15956029394746e5c7f","subtreeSha":"17CD587D4B6D7CDA52F31624C01CC0674EBB27CA977E50F1F0B153AA7F0AE359","lastSyncedAt":"2026-10-15T13:11:53.672149Z"},"reviewedAt":"2026-10-15T13:12:40.870904Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/testdouble/han/tree/main/han-documentation/skills/architectural-decision-record"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install testdouble-han@llmmart"},{"target":"git","command":"git clone https://github.com/testdouble/han.git"}]}