76 lines
4.0 KiB
Markdown
76 lines
4.0 KiB
Markdown
# Spec: ADR Migration
|
||
|
||
## Purpose
|
||
|
||
Defines how existing ADR-like content in a project is migrated into the standard `os-adr` format: mechanical shape detection with a safe fallback, a strict mechanical/LLM field-mapping boundary, a single uncertainty-flagging mechanism, non-destructive dual-existence conversion, and a pilot gate before broad rollout.
|
||
|
||
## Requirements
|
||
|
||
### Requirement: Shape detection with a fallback
|
||
The migration tooling SHALL mechanically detect existing ADR-like content and classify it into
|
||
the surveyed shapes — numbered per-file directories, dated single files, monolithic
|
||
multi-decision files, prose embedded in other docs — plus an `unrecognized` fallback
|
||
classification. Unrecognized content SHALL be reported for manual handling, never auto-converted.
|
||
|
||
#### Scenario: Known shape detected
|
||
- **WHEN** detection runs on a project with a monolithic multi-decision file
|
||
- **THEN** the file is classified as monolithic and its individual decisions are enumerated as
|
||
migration units
|
||
|
||
#### Scenario: Unknown shape falls back safely
|
||
- **WHEN** detection encounters ADR-like content matching no known shape
|
||
- **THEN** it is classified `unrecognized` and listed in the report without any conversion
|
||
attempt
|
||
|
||
### Requirement: Mechanical/LLM field-mapping boundary
|
||
During conversion, fields that are structurally unambiguous in the source (Status and Date from
|
||
frontmatter or clear headings; title; ID assignment; source provenance) SHALL be filled
|
||
mechanically. Only interpretive fields (Consequences, Alternatives rejected, monolithic-file
|
||
decision splitting) MAY be LLM-filled, and every LLM-filled field SHALL be flagged. The
|
||
migration SHALL never invent a Decision or Context field absent from the source — such fields
|
||
SHALL carry an explicit not-stated-in-source marker and lower the file's confidence.
|
||
|
||
#### Scenario: Unambiguous field filled mechanically
|
||
- **WHEN** a source ADR has a `Status: Accepted` heading and a date
|
||
- **THEN** the converted file's `status` and `date` are set without any LLM call
|
||
|
||
#### Scenario: Missing core field is not invented
|
||
- **WHEN** a source decision has no discernible Context
|
||
- **THEN** the converted Context section contains a not-stated-in-source marker and the file is
|
||
flagged low-confidence
|
||
|
||
### Requirement: Single uncertainty-flagging mechanism
|
||
Migration uncertainty SHALL be surfaced through exactly one mechanism: a
|
||
`migration_confidence: low|medium|high` frontmatter field per converted file, plus one
|
||
migration report file (`docs/adr/migration-report.md`) summarizing per-file confidence, the
|
||
source-to-new mapping, and the overall low-confidence flag rate. Scattered inline uncertainty
|
||
comments SHALL NOT be used.
|
||
|
||
#### Scenario: Report aggregates confidence
|
||
- **WHEN** a migration completes
|
||
- **THEN** the report lists every converted file with its confidence, its source location, and
|
||
the overall flag rate
|
||
|
||
### Requirement: Non-destructive, dual-existence conversion
|
||
Migration SHALL only write new files under `docs/adr/`; existing ADR content SHALL never be
|
||
deleted, moved, or edited by the migration. Removal of the old system SHALL happen only as an
|
||
explicit, separate, user-approved step offered after the migration report exists.
|
||
|
||
#### Scenario: Old system untouched
|
||
- **WHEN** a migration run completes
|
||
- **THEN** every pre-existing ADR source file is byte-identical to its pre-migration state
|
||
|
||
#### Scenario: Deletion requires explicit approval
|
||
- **WHEN** the user has not explicitly approved old-system removal
|
||
- **THEN** no tooling path deletes the old content, and the removal offer appears only after the
|
||
report is available for review
|
||
|
||
### Requirement: Pilot gate before broad rollout
|
||
The migration SHALL be piloted on 2–3 real surveyed projects, and the low-confidence flag rate
|
||
SHALL be measured against an explicit threshold recorded at pilot time before the heuristics are
|
||
treated as good enough for wider rollout.
|
||
|
||
#### Scenario: High flag rate blocks rollout
|
||
- **WHEN** a pilot run's low-confidence rate exceeds the recorded threshold
|
||
- **THEN** the heuristics are tightened and the pilot re-run before migrating further projects
|