61 lines
2.7 KiB
Markdown
61 lines
2.7 KiB
Markdown
---
|
|
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.
|