---
description: Non-destructively convert a project's existing ADR-like content (numbered files, dated files, monolithic decision logs, prose-embedded decisions) into the standard docs/adr/ format. Sources are never touched; uncertainty is flagged via migration_confidence + a migration report. Invoked by `/os-adr:migrate`.
---

Migrate existing decision records into the standard ADR format. The mechanical work (detection,
splitting on unit headings, heuristic field fill, numbering, indexing, report generation) is all
done by the CLI; your job is ONLY to fill the interpretive fields the CLI's manifest explicitly
lists, and to present the results.

## 1. Detect (report-only)

```bash
ruby ${CLAUDE_PLUGIN_ROOT}/bin/adr-detect --root <project-root>
```

Show the user the detected units and shapes (`numbered_per_file`, `dated_single_file`,
`topic_single_file`, `monolithic`, `prose_embedded`, `unrecognized`). Confirm they want to
proceed before converting anything.

## 2. Mechanical pass

```bash
ruby ${CLAUDE_PLUGIN_ROOT}/bin/adr-migrate --root <project-root>
```

This writes new ADRs under `docs/adr/` only (sources stay byte-identical), heuristic-fills
structurally unambiguous fields (status, date, title, ID, provenance, exactly-matching
sections), regenerates the index, writes `docs/adr/migration-report.md`, and prints a JSON
**work manifest**.

## 3. LLM fill — manifest-listed fields ONLY

For each manifest entry with non-empty `llm_fields`, write the listed fields (`consequences`,
`alternatives`, sometimes `status`) from that entry's `source_material` — summarize what the
source actually says, don't invent. Rules:

- Fill ONLY fields the manifest lists. Fields marked `_not stated in source_` (Decision,
  Context) must NEVER be invented — leave them; the file stays flagged low-confidence.
- `status` fills must be one of Proposed/Accepted/Superseded/Deprecated.

Hand the results back to the core for writing — do not edit the ADR files directly:

```bash
# fills.json: {"docs/adr/0001-x.md": {"consequences": "...", "alternatives": "..."}}
ruby ${CLAUDE_PLUGIN_ROOT}/bin/adr-migrate --root <project-root> --apply-fills fills.json
```

(The core only accepts fills into pending-marker fields, so a stray key is a no-op.)

## 4. Present the report

Show `docs/adr/migration-report.md`: per-file confidence, source mapping, the low-confidence
flag rate, and any `unrecognized` sources needing manual handling. Suggest the user review
low-confidence files.

## 5. Old-system deletion — separate, explicit approval only

Do NOT delete, move, or edit the old decision files as part of migration. Only after the user
has reviewed the report, offer removal of the old system as a distinct step, and perform it only
on their explicit approval of the specific files to remove.