jared
/
cc-os
1
0
Fork 0
Code Issues 18 Pull Requests Packages Projects Releases Wiki Activity
cc-os/openspec/specs/adr-retrieval/spec.md

2.8 KiB
Raw Permalink Blame History

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