# ADR create/update prompt

Create or update a single Architecture Decision Record.

## Significance scan

If the task was not already flagged as ADR-worthy, confirm the decision meets the significance threshold in `rules/10-adr-significance-scan.md`. If unsure, ask before drafting.

## Hard rules

1. **One ADR per commit** — never bundle multiple ADRs or unrelated changes
2. **Commit type:** `adr(<category>): <short summary>` for new decisions; `docs(adr):` / `fix(adr):` for non-semantic maintenance only
3. **Index:** update `docs/adr/INDEX.md` in the same commit as a new, amending, or superseding ADR
4. **Immutability:** Accepted/Amended/Rejected ADRs are immutable in substance — read `rules/08-adr-editing-evolution.md` and ADR-0021

## Editing Accepted ADRs

**Allowed (maintenance only):** typos, broken links, same-intent path fixes, formatting — must not change Decision, Context, or Consequences meaning.

**Forbidden:** any semantic change — create a **new** ADR (**amend** or **supersede**).

If the user asks to "update" an Accepted ADR:

1. Do **not** rewrite the old ADR body
2. Choose path:
   - **Amend** (core decision still holds): new ADR with `## Amends`; base → `Status: Amended`, `## Amended by`
   - **Supersede** (core decision no longer valid): new ADR with `## Supersedes`; old → `Status: Superseded`, `Superseded by`
3. Use `adr(<category>):` commit for the new decision

## Allowed in ADR commit (`adr(...)`)

- One **new** ADR file, or amend/supersession link updates tied to a new ADR
- `docs/adr/INDEX.md` updates
- Old ADR status/link fields for amend or supersession only

## Forbidden in ADR commit

- Implementation code
- Unrelated documentation
- Semantic rewrites of existing Accepted ADR bodies (use new ADR + amend or supersede)
- Multiple independent ADRs

## Template

Use `templates/adr/adr-template.md`.

## External proposals and web source intake

Upstream tools (other AI assistants, design docs, pasted drafts) may use **non-A2C citation styles**. That is fine at intake — **normalize before commit** to this repository's contract.

### Common intake shapes

| Intake | Examples |
|--------|----------|
| Custom tags + separate mapping | `[web:3]`, `[web:scrapy]`, sidecar `sources.md` |
| Inline footnotes | `[^1]` + `[^1]: https://…` at file bottom |
| Raw URLs | `https://docs.example/…` inline |
| Mixed | footnotes in ADR body + URL list in another file |

### Normalize to A2C format (before commit)

1. Read [rules/15-web-source-tags.md](../../rules/15-web-source-tags.md) and [docs/web-source-mapping.md](../../docs/web-source-mapping.md).
2. Extract every **new** external URL (or infer URL from footnote definitions).
3. For each URL: reuse existing `web:NNN` when the mapping already has that canonical URL; otherwise allocate the **next free sequential** ID.
4. Rewrite ADR/doc body: replace footnotes, raw URLs, and foreign tags with **`[web:NNN]`** inline (three-digit zero-padded).
5. Add or update matching `### web:NNN — Label` entries in `docs/web-source-mapping.md` in the **same commit**.
6. Run `python scripts/check_web_source_tags.py` (or `pre-commit run check-web-sources` when enabled).
7. On unmapped tags only: run [prompts/maintenance/web-source-recovery.md](../maintenance/web-source-recovery.md) — **propose only**; human confirms before commit.

### Do not

- Commit foreign citation styles as the stored contract when `[web:NNN]` + mapping is available.
- Bulk-convert legacy inline URLs in **Accepted** ADRs (soft adoption — ADR-0011).
- Drop duplicate footnote blocks without merging URLs into the central mapping.

Portal builds may render `[web:NNN]` as external links via docs-portal; git source stays tag + mapping only.

## Categories (examples)

`workflow`, `build`, `layout`, `docs`, `security`, `data`

## Task

> Describe the single architecturally significant decision to record, OR the maintenance edit (must match allowed maintenance rules).

## Output

1. ADR draft or explicit maintenance diff (one ADR only)
2. INDEX.md diff if applicable
3. Exact commit message (`adr(...)` or `docs(adr):` / `fix(adr):`)
4. Stop — do not proceed to implementation