servicenow-atlas: Skill for Claude Code

When to use

Create an ADR when you make a decision that is:

• Significant — affects multiple modules, backends, or the build process
• Non-obvious — the rationale won't be immediately clear to future readers
• Costly to reverse — changing it later would require substantial rework
• Architecturally binding — constrains future design choices

Examples from this project's history that should have been ADRs:

• Choosing MLX over CoreML for Apple Silicon
• Using snapshot_download instead of cached_file for ONNX tokenizer loading
• Reducing CI model from BGE-base (768-dim) to BGE-small (384-dim) for timeout reasons
• Choosing int8 quantisation over FP32 for CPU builds

Do NOT create ADRs for:

• Bug fixes
• Routine dependency upgrades
• Cosmetic refactors
• Decisions documented entirely by code comments

ADR format

Each ADR is a markdown file at docs/adr/NNNN-title-with-dashes.md.

File name

NNNN-title-with-dashes.md

Where NNNN is the next available number, zero-padded to 4 digits.

Frontmatter

---
date: 2026-06-22
status: accepted  # proposed | accepted | deprecated | superseded
supersedes:  # optional: ADR number this replaces
superseded_by:  # optional: ADR number that replaces this
---

Template

---
date: <YYYY-MM-DD>
status: <proposed|accepted|deprecated|superseded>
---

# <Number>. <Title>

## Context

What is the problem we are solving? What constraints or forces are at play?
Include relevant background, requirements, and trade-offs.

## Decision

What did we decide? State it clearly and concretely.

## Rationale

Why this option over the alternatives? List 2–3 options considered and why
each was or wasn't chosen.

## Consequences

What becomes easier or harder as a result of this decision?
What does this decision enable or foreclose?

## Compliance

How will future code or CI enforce this decision? (optional)

Where to store

docs/adr/
├── index.md       # Table of contents, generated
├── 0001-mlx-over-coreml.md
└── 0002-snapshot-download-for-tokenizer.md