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

description

Retrieve the architecture decision records relevant to files, components, or a topic being worked on — callable at any point mid-task, not just at session start. Use unprompted WHEN you are about to make an architecture-level choice or change/replace an approach that already exists in the codebase (a persistence choice, a protocol, a library, a convention, an error-handling strategy) — a prior decision may already cover it. Invoked by `/os-adr:find`.

Find the ADRs relevant to what is being worked on. Retrieval is deterministic-first: run the CLI, then apply judgment ONLY to the candidates it returns — never read/rank the full ADR corpus yourself.

1. Run the deterministic CLI

ruby ${CLAUDE_PLUGIN_ROOT}/bin/adr-find --root <project-root> \
  --paths <comma-separated file/dir paths being edited> \
  --components <comma-separated component names>   # optional

The CLI layers: frontmatter path/component matching → Accepted-only status filter → one-hop Graphify graph expansion of the query paths (automatic when graphify-out/graph.json exists; silently skipped otherwise). Add --all-statuses only when history matters (e.g. "why was X superseded?").

2. Judge the candidate set

Read the returned candidate files (they are few) and decide which actually bear on the task. matched_on tells you why each surfaced (path, graph, component). Prefer direct path matches; treat graph matches as "nearby decisions worth a look".

3. Act on what you find

• If an Accepted ADR covers the approach the in-progress change is altering or replacing, you are reversing a recorded decision — and a reversal is itself a decision that must be recorded, not just implemented. Surface the specific ADR (ID + title + the constraint), and make the recording offer explicit and direct in your reply — state plainly "this reverses ADR-NNNN; I'll record a superseding ADR via /os-adr:create" (or create it outright). Do not bury the ADR as a parenthetical inside an option list; every path you offer that changes the decided behavior must carry the explicit superseding-ADR step.
• If a candidate merely informs the work, cite it and continue.
• If the CLI returns nothing, say so — do not fall back to sweeping docs/adr/ unless the user asks; an empty result usually means no decision governs those paths (or affected-paths frontmatter is missing on older ADRs — worth mentioning once).