cc-os/plugins/os-adr/skills/migrate/SKILL.md

name	description
migrate	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)

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

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:

# 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.