54 lines
2.8 KiB
Markdown
54 lines
2.8 KiB
Markdown
|
# Spec: ADR Retrieval
|
|||
|
|
|
|||
|
|
## Purpose
|
|||
|
|
|
|||
|
|
Defines how relevant ADRs are found by the `os-adr` plugin: deterministic-first layered narrowing (frontmatter match, status filter, Graphify expansion) with AI judgment applied only to the narrowed candidate set, graceful degradation without a project graph, a mid-task-callable query surface, and eval-readiness sketches accompanying the build.
|
|||
|
|
|
|||
|
|
## Requirements
|
|||
|
|
|
|||
|
|
### Requirement: Deterministic-first retrieval layering
|
|||
|
|
ADR retrieval SHALL narrow candidates through ordered layers: (1) path/component match of query
|
|||
|
|
inputs against each ADR's `affected-paths`/`affected-components` frontmatter; (2) status filter
|
|||
|
|
admitting only `Accepted` ADRs by default, with an explicit override to include other statuses;
|
|||
|
|
(3) Graphify graph traversal when a project graph exists; (4) AI judgment applied only to the
|
|||
|
|
already-narrowed candidate set. AI judgment SHALL never be applied to the full ADR corpus.
|
|||
|
|
|
|||
|
|
#### Scenario: Path match narrows first
|
|||
|
|
- **WHEN** retrieval is queried with file paths being edited
|
|||
|
|
- **THEN** ADRs whose `affected-paths` match are selected before any model involvement
|
|||
|
|
|
|||
|
|
#### Scenario: Default status filter
|
|||
|
|
- **WHEN** retrieval runs without an override
|
|||
|
|
- **THEN** only `Accepted` ADRs appear in the candidate set
|
|||
|
|
|
|||
|
|
#### Scenario: AI sees only the narrowed set
|
|||
|
|
- **WHEN** the AI-judgment layer runs
|
|||
|
|
- **THEN** it receives only the candidates surviving layers 1–3, not the full corpus
|
|||
|
|
|
|||
|
|
### Requirement: Graph layer degrades gracefully
|
|||
|
|
WHEN no `graphify-out/` project graph exists (or ADRs are not yet indexed as graph nodes),
|
|||
|
|
retrieval SHALL still function using layers 1, 2, and 4, without error.
|
|||
|
|
|
|||
|
|
#### Scenario: No project graph present
|
|||
|
|
- **WHEN** retrieval runs in a project that has never been onboarded to Graphify
|
|||
|
|
- **THEN** results are produced from frontmatter matching and status filtering alone
|
|||
|
|
|
|||
|
|
### Requirement: Mid-task-callable query surface
|
|||
|
|
Retrieval SHALL be exposed as a `find` skill (`/os-adr:find`) backed by a deterministic CLI,
|
|||
|
|
callable at any point during a task — not only at SessionStart — so an agent can check
|
|||
|
|
in-progress work against existing decisions.
|
|||
|
|
|
|||
|
|
#### Scenario: Query during a task
|
|||
|
|
- **WHEN** an agent mid-task invokes `/os-adr:find` with the files or topic it is working on
|
|||
|
|
- **THEN** it receives the relevant Accepted ADR candidates for those inputs
|
|||
|
|
|
|||
|
|
### Requirement: Eval-readiness sketches accompany the build
|
|||
|
|
Held-out evaluation scenario shapes (write-trigger and retrieval) SHALL be sketched in a design
|
|||
|
|
doc before the plugin skeleton is finalized, and any plugin surface those sketches require SHALL
|
|||
|
|
be part of the initial build. The evaluation itself SHALL NOT be part of this change.
|
|||
|
|
|
|||
|
|
#### Scenario: Sketches exist before skeleton freeze
|
|||
|
|
- **WHEN** the plugin skeleton is finalized
|
|||
|
|
- **THEN** a scenario-sketch document exists covering at least one write-trigger and one
|
|||
|
|
retrieval scenario shape
|