--- name: dld-lookup description: Look up decisions by ID, tag, code path, or keyword. IMPORTANT — use this proactively whenever you encounter `@decision` annotations in code you are about to read or modify. compatibility: Requires Node.js 22+. metadata: dld-kit-version: "1.0.0" --- # /dld-lookup — Look Up Decisions You are looking up decision records. This skill is used in two ways: 1. **Proactively by you (the AI agent)** — whenever you encounter `@decision(DL-XXX)` annotations in code you're reading or about to modify, look up the decision to understand the rationale before proceeding. This is not optional. 2. **On request by the developer** — to query decisions by ID, tag, code path, or keyword. ## Commands The commands below run the `dld` CLI bundled with the dld-common skill, and need Node.js 22+. `` stands for the absolute path of this skill's directory. If `/../dld-common/scripts/dld.mjs` does not exist, stop and tell the user to install the dld-common skill: `npx skills add jimutt/dld-kit --skill dld-common`. This skill uses: `related-decisions`. ## Prerequisites Check that `dld.config.yaml` exists at the repo root. If not, tell the user to run `/dld-init` first and stop. Read `dld.config.yaml` to understand the project structure (flat vs namespaced, decisions directory). The decisions directory path can be resolved by reading the `decisions_dir` field from `dld.config.yaml`. Decision records (DL-*.md) live in the `records/` subdirectory under the decisions directory. ## Query modes Parse the user's input to determine the query type: ### By ID: `/dld-lookup DL-047` Find and read the decision file `DL-047.md`. Search the records subdirectory (`decisions/records/`, including namespace subdirectories) for the file. Then list the decisions related to it: ```bash node "/../dld-common/scripts/dld.mjs" related-decisions DL-047 ``` Each line is `\t\t\t`. `amended-by` and `superseded-by` lines are later decisions that change this one; `amends` and `supersedes` lines are the earlier decisions it changes. A status of `missing` means no record has that ID. If the decision has been amended or superseded (any `amended-by` or `superseded-by` line whose status is `accepted`): 1. Say so **before** the record's content, naming the newer decisions. 2. Read each of them, and summarise what its Decision section changes about this one. 3. Where they differ, follow the newest accepted decision, not this one. Follow chains: when an `amended-by` or `superseded-by` decision is itself `superseded`, run `node "<skill-dir>/../dld-common/scripts/dld.mjs" related-decisions` on it and use its `superseded-by` successor instead, until you reach an `accepted` decision. A `proposed` amending or superseding decision is planned, not in effect: mention it, but keep following the accepted decisions. Then display the full decision record, followed by its other relations (the decisions it amends or supersedes) if there are any. ### By tag: `/dld-lookup tag:payment-gateway` Scan all decision files and find those with the matching tag in their YAML frontmatter `tags` field. Display a summary table, then offer to show full details for any specific decision: ``` Found 3 decisions tagged `payment-gateway`: | ID | Title | Status | |----|-------|--------| | DL-045 | Payment gateway retry strategy | accepted | | DL-046 | Idempotency key format | proposed | | DL-047 | Gateway timeout handling | proposed | Would you like to see the full details for any of these? ``` ### By code path: `/dld-lookup path:src/billing/vat.ts` Scan all decision files and find those with a matching `path` in their `references` field. Match both exact paths and partial paths (e.g., `vat.ts` should match `src/billing/vat.ts`). Display results the same way as tag lookup. ### By keyword: `/dld-lookup <search terms>` If the input doesn't match the `DL-NNN`, `tag:`, or `path:` patterns, treat it as a keyword search. Search across: - Decision titles - Decision body content (Context, Decision, Rationale, Consequences sections) - Tags Display results the same way as tag lookup. ## Proactive usage (encountering `@decision` annotations) When you encounter `@decision(DL-XXX)` in code — whether you are reading, modifying, or reviewing it — you MUST look up the referenced decision before proceeding. This applies to all interactions with annotated code, not just when explicitly asked. After reading the decision, and the decisions that amend or supersede it (see "By ID" above): 1. **Understand** the rationale behind the annotated code 2. **Assess** whether your planned changes are compatible with the decision 3. **If they conflict** — stop and inform the user. Explain the conflict and suggest recording a new decision via `/dld-decide` that supersedes the existing one. Do not silently modify code in a way that contradicts an active decision. 4. **If they're compatible** — proceed with the modification This is the core DLD feedback loop — `@decision` annotations are mechanical triggers that ensure design rationale is consulted before code is changed. Annotations use the `annotation_prefix` from `dld.config.yaml` (`@decision` by default); the examples here show the default.