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
|