dld-kit 1.0.0-rc.1

package/skills/dld-decide/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: dld-decide
+description: Record a single development decision as a markdown file with YAML frontmatter. Collects context, rationale, and code references interactively.
+compatibility: Requires Node.js 20+ and git.
+metadata:
+  dld-kit-version: "1.0.0-rc.1"
+---
+<!-- Generated by dld-kit from templates/skills/dld-decide/SKILL.md. Do not edit: updating the skills overwrites this file. -->
+
+# /dld-decide — Record a Decision
+
+You are helping the developer record a development decision. This should be a focused, low-ceremony conversation — not an interrogation.
+
+## Interaction style
+
+Use the `AskUserQuestion` tool for all questions and prompts. This provides a structured input experience for the user rather than waiting for freeform replies.
+
+## Commands
+
+The commands below run the `dld` CLI bundled with the dld-common skill, and need Node.js 20+. `<skill-dir>` stands for the absolute path of this skill's directory. If `<skill-dir>/../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: `next-id`, `create-decision`, `update-status`, `regenerate-index`.
+
+## Prerequisites
+
+Check that `dld.config.yaml` exists at the repo root. If not, tell the user to run `/dld-init` first and stop.
+
+## Read project context
+
+1. Read `dld.config.yaml` to understand the project structure (flat vs namespaced, decisions directory, namespaces list)
+2. Read `decisions/PRACTICES.md` if it exists — be aware of project conventions when helping structure the decision
+3. For namespaced projects, also read `decisions/records/<namespace>/PRACTICES.md` if it exists for the relevant namespace
+
+## Conversation flow
+
+### 1. Collect the decision
+
+If the user provided context with the skill invocation, use it. Otherwise ask:
+
+> What decision are you recording? Tell me what you decided, why, and what code it affects.
+
+Listen for:
+- **What** was decided (the decision itself)
+- **Why** (the rationale — what problem it solves, what alternatives were considered)
+- **What it affects** (code areas, components, modules)
+
+### 2. Ask clarifying questions (if needed)
+
+Only ask follow-up questions if the rationale or scope is genuinely unclear. Maximum 3-5 questions total. Don't interrogate — if the developer gave enough context, move on.
+
+Good reasons to ask:
+- The rationale is missing or unclear
+- There might be alternatives worth noting
+- The scope of affected code isn't clear
+- There are obvious consequences worth recording
+
+### 3. Check for related decisions
+
+Scan existing decision files for potential relationships:
+- Decisions that reference the same code paths
+- Decisions with overlapping tags
+- Decisions that this one might supersede or amend
+
+If you find related decisions, mention them and ask whether this decision **supersedes** (fully replaces) or **amends** (partially modifies) any of them. A superseded decision gets marked as `superseded` and is no longer active. An amended decision stays `accepted` — the amendment changes part of its scope while the rest remains in effect.
+
+### 4. Determine namespace (namespaced projects only)
+
+If the project is namespaced, determine which namespace this decision belongs to. Infer from the code references if possible, otherwise ask.
+
+### 5. Assign ID
+
+Run `next-id`:
+```bash
+node "<skill-dir>/../dld-common/scripts/dld.mjs" next-id
+```
+
+This outputs the next available ID (e.g., `DL-004`).
+
+### 6. Create the decision record
+
+Compose the markdown body with the relevant sections (Context, Decision, Rationale, Consequences). Omit sections that aren't relevant, but always include Context and Decision.
+
+Then run `create-decision`, piping the body via `printf` with `\n` for newlines (do **not** use literal newlines in the body argument — use `\n` escape sequences so the entire command stays on one logical line):
+```bash
+printf "## Context\n\nWhat prompted this decision.\n\n## Decision\n\nWhat was decided.\n\n## Rationale\n\nWhy this choice.\n\n## Consequences\n\nWhat becomes easier or harder." | node "<skill-dir>/../dld-common/scripts/dld.mjs" create-decision \
+  --id "DL-NNN" \
+  --title "Short descriptive title" \
+  --namespace "billing" \
+  --tags "tag1, tag2" \
+  --supersedes "DL-003, DL-007" \
+  --amends "DL-005" \
+  --body-stdin
+```
+
+Flags `--namespace`, `--tags`, `--supersedes`, `--amends` are optional. The command creates the file with YAML frontmatter and the body content, and outputs the file path.
+
+> **Note:** If the body contains literal `%` characters, escape them as `%%` (printf format string requirement).
+
+If this decision supersedes others, also update their status:
+```bash
+node "<skill-dir>/../dld-common/scripts/dld.mjs" update-status DL-003 superseded
+```
+
+**Do not** update the status of amended decisions — they stay `accepted`.
+
+### 7. Regenerate INDEX.md
+
+```bash
+node "<skill-dir>/../dld-common/scripts/dld.mjs" regenerate-index
+```
+
+### 8. Suggest next steps
+
+> Decision **DL-NNN** recorded as `proposed`.
+>
+> Next steps:
+> - `/dld-adjust` — refine the decision before implementing
+> - `/dld-implement DL-NNN` — implement this decision
+> - `/dld-decide` — record another decision

package/skills/dld-implement/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: dld-implement
+description: Implement one or more proposed decisions. Makes code changes, adds `@decision` annotations, and updates decision status.
+compatibility: Requires Node.js 20+ and git.
+metadata:
+  dld-kit-version: "1.0.0-rc.1"
+---
+<!-- Generated by dld-kit from templates/skills/dld-implement/SKILL.md. Do not edit: updating the skills overwrites this file. -->
+
+# /dld-implement — Implement Decisions
+
+You are implementing one or more `proposed` decisions by making code changes, adding `@decision` annotations, and updating the decision records.
+
+## Commands
+
+The commands below run the `dld` CLI bundled with the dld-common skill, and need Node.js 20+. `<skill-dir>` stands for the absolute path of this skill's directory. If `<skill-dir>/../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: `update-status`, `verify-annotations`, `regenerate-index`.
+
+## Prerequisites
+
+1. Check that `dld.config.yaml` exists at the repo root. If not, tell the user to run `/dld-init` first and stop.
+2. Parse the user's input to identify which decision(s) to implement:
+   - Specific IDs: `DL-005`, `DL-005 DL-006`
+   - By tag: `tag:payment-gateway`
+   - **No arguments:** If the user runs `/dld-implement` without specifying decisions, find all decisions with `status: proposed` in the records subdirectory (`decisions/records/`) and implement all of them.
+3. Read each referenced decision file. Verify they exist and have `status: proposed`. If a decision is already `accepted`, tell the user and skip it. If it doesn't exist, report the error.
+
+## Read project context
+
+1. Read `dld.config.yaml` for project structure
+2. Read `decisions/PRACTICES.md` if it exists — **this is where practices guidance is most important**. Apply the project's testing approach, code style, error handling patterns, and architecture conventions when writing code.
+3. For namespaced projects, also read `decisions/records/<namespace>/PRACTICES.md` for namespace-specific practices
+
+## Implementation
+
+### Batch vs. single implementation
+
+When multiple decisions are requested, decide whether to implement them individually or as a batch:
+
+- **Batch together** decisions that are tightly coupled — they touch the same code, share types, or depend on each other so heavily that implementing one without the others would produce incomplete or throwaway code (e.g., a data model + its validation + its state machine).
+- **Implement separately** decisions that are independent — they touch different areas of the codebase and can stand on their own.
+
+When batching, implement all the code together, add annotations for all decisions, then update each decision record and status individually in step 4.
+
+### 1. Understand the decision(s)
+
+Read each decision record carefully. Understand:
+- What was decided
+- The rationale and constraints
+- The code areas referenced
+- Any superseded or amended decisions (read those too for context on what changed)
+
+### 2. Make code changes
+
+Implement the decision(s) by modifying the codebase. Follow the practices manifest if one exists.
+
+**Refining decisions during implementation:** While implementing, you may discover details that weren't anticipated during planning — a specific threshold value, an edge case handling approach, or a refinement to the original design. Since the decision is still in `proposed` status, it is **mutable** and can be updated:
+
+- **Small refinements** (implementation details, specific values, edge cases that don't change the decision's intent) — update the decision record inline. Amend the Decision, Rationale, or Consequences sections as needed. This is expected and encouraged.
+- **Major discoveries** (a fundamentally different approach is needed, or an entirely new design concern surfaces) — stop and suggest the user run `/dld-decide` to record a separate decision. If the new discovery invalidates the current decision, it may need to be superseded instead.
+
+The boundary: if the discovery changes the *intent* of the decision, it's a new decision. If it refines the *implementation details*, update the current one.
+
+### 3. Add `@decision` annotations
+
+**This step is mandatory.** Every implemented decision MUST have at least one `@decision(DL-NNN)` annotation in the source code. Updating the decision record's `references` field alone is not sufficient. The annotation in code is what triggers AI agents to look up the decision before modifying the annotated code.
+
+Add `@decision(DL-NNN)` annotations to the code you modified or created. Place annotations in comments near the relevant code.
+
+**Where to annotate:**
+- Functions, methods, or classes that embody the decision
+- Configuration or constants that were chosen based on the decision
+- Key logic branches where the decision's rationale matters
+
+**Annotation format** (adapt comment syntax to the language):
+```typescript
+// @decision(DL-012)
+function calculateVAT(order: Order): Money {
+  // ...
+}
+```
+
+```python
+# @decision(DL-012)
+def calculate_vat(order: Order) -> Money:
+    ...
+```
+
+**Guidelines:**
+- Annotate at the declaration level, not every line
+- One annotation per decision per code location
+- Multiple decisions can annotate the same code: `// @decision(DL-012) @decision(DL-015)`
+- Use the `annotation_prefix` from `dld.config.yaml` (default: `@decision`)
+
+**Keep annotations lean — the decision record is the single source of truth.**
+
+The point of `@decision(DL-NNN)` is to keep the rich context (rationale, constraints, alternatives, consequences) in the decision record, *not* scattered through the code. The annotation is a pointer, not a summary. Do not let implementing a decision turn into a comment-writing exercise.
+
+- **Default to the bare annotation.** `// @decision(DL-012)` on its own is the norm and is usually all you need.
+- **Do not restate the decision's context.** Don't paraphrase the rationale, the alternatives considered, or the "why" in comments. That duplicates the record, creates a second source of truth, and drifts the moment the decision is adjusted.
+- **Avoid "because" comments paired with the annotation.** `// @decision(DL-012)` already means "the reasoning lives in DL-012." Writing `// We use X because Y (see DL-012)` defeats the purpose — drop the "because Y."
+- **Only add a further comment when the *code itself* is genuinely non-obvious** — a subtle invariant, a non-intuitive workaround, a non-local ordering dependency. Such a comment should explain *what the code is doing*, never *why the decision was made* (that's the record's job).
+
+When in doubt, leave it out — a reader who wants the "why" follows the annotation to the decision record.
+
+### 4. Update decision records
+
+For each implemented decision:
+
+1. **Update the `references` field** in the decision record's YAML frontmatter. Edit the file directly — add the code paths and symbols that were annotated. Example:
+   ```yaml
+   references:
+     - path: src/billing/vat.ts
+       symbol: calculateVAT
+     - path: src/billing/vat.test.ts
+   ```
+
+2. **Update status** from `proposed` to `accepted`:
+   ```bash
+   node "<skill-dir>/../dld-common/scripts/dld.mjs" update-status DL-NNN accepted
+   ```
+
+### 5. Verify annotations
+
+After updating all decision records, run `verify-annotations` to confirm every implemented decision has at least one `@decision` annotation in the codebase:
+
+```bash
+node "<skill-dir>/../dld-common/scripts/dld.mjs" verify-annotations DL-005 DL-006
+```
+
+Pass all the decision IDs that were implemented. If any are missing annotations, the command will report them and exit with an error. Go back and add the missing annotations before proceeding.
+
+### 6. Review code changes
+
+Check `dld.config.yaml` for the `implement_review` key. If it is set to `false`, skip this step entirely. If it is `true` or absent (default: enabled), proceed.
+
+Launch a subagent to review all code changes for correctness and security. Use the `Agent` tool (also called `AgentTool`) with a prompt constructed from the template below, replacing all `{{placeholders}}` with actual values:
+
+```
+You are reviewing code changes for the {{project_name}} project before committing. The changes implement {{decision_count}} decisions ({{decision_range}}) covering:
+
+{{decision_summaries}}
+
+The project uses:
+{{tech_stack_summary}}
+
+Review these files for:
+- Correctness (logic errors, edge cases)
+- Security (SQL injection, directory traversal, XSS, etc.)
+- Consistency with existing patterns and conventions
+- Type safety issues
+- Missing error handling
+- Any code that could be simplified
+
+Files to review (read all of them):
+{{file_list}}
+
+Also read the practices doc at {{practices_path}}
+
+Focus on the changes made for these decisions; report pre-existing issues only where the new code interacts with them. Before reporting consistency findings, examine similar existing code in the repo to learn its conventions.
+
+Do NOT make any changes. Only report findings. Be concise — focus on actual issues, not style preferences ({{linter_name}} handles style).
+
+Report each finding in this format:
+
+### [SEVERITY] Short title
+- Location: `path/to/file.ext:42`
+- Description: what is wrong and why it matters
+- Recommendation: specific, actionable fix
+
+Group findings by severity:
+- Critical (must fix): incorrect behavior, data loss, or an exploitable vulnerability
+- Moderate (should fix): bugs in edge cases, missing error handling that can plausibly trigger
+- Minor (nice to have): simplifications and small improvements
+```
+
+**Filling in the placeholders:**
+- `{{project_name}}` — from `dld.config.yaml` or the repo directory name
+- `{{decision_count}}` and `{{decision_range}}` — count and IDs of the decisions just implemented (e.g., "3 decisions (DL-005 – DL-007)")
+- `{{decision_summaries}}` — one-line summary of each decision's title and intent
+- `{{tech_stack_summary}}` — languages, frameworks, and key libraries from the project (infer from `dld.config.yaml`, `package.json`, or equivalent)
+- `{{file_list}}` — all files you created or modified during steps 2–4
+- `{{practices_path}}` — path to `decisions/PRACTICES.md` (or namespace-specific practices if applicable). Omit the line if no practices file exists.
+- `{{linter_name}}` — the project's linter (e.g., ESLint, Ruff). If unknown, use "the project linter"
+
+**Launching the subagent is requested by the user.** Some agent harnesses carry a standing instruction not to spawn subagents unless the user asked for one. That condition is met here: the user asked by running this skill in a project whose `implement_review` setting is enabled. The request does not need to be repeated in conversation, and this step is not an unprompted fan-out — it is one review agent, at a fixed point, that the project opted into.
+
+**If the subagent genuinely cannot run** — the tool is unavailable, or the user denies the call — do not silently skip the review. Do it inline instead, and make it a deliberate pass rather than a recollection: re-read each changed file from disk and work through the checklist above against what is actually written. Then state in your final report that the review ran inline rather than in a subagent, and why. An inline review is the author checking their own work; it is weaker than a fresh-context review at catching assumptions baked in while implementing, and the user needs to know which one they got.
+
+**Acting on findings:**
+- **Critical** — fix before proceeding
+- **Moderate** — fix unless you disagree with the finding (use your judgment)
+- **Minor** — skip unless trivial to address
+
+**Note:** The review subagent operates with limited context and may flag false positives or misunderstand project-specific patterns. Use your own judgment — you have fuller context from having just written the code. If you're uncertain whether a finding warrants a fix, ask the user before making changes.
+
+If you made fixes, re-run `verify-annotations` from step 5 to ensure annotations are still intact.
+
+### 7. Regenerate INDEX.md
+
+```bash
+node "<skill-dir>/../dld-common/scripts/dld.mjs" regenerate-index
+```
+
+### 8. Suggest next steps
+
+> Implemented and accepted: **DL-NNN** (<title>)
+>
+> Code changes:
+> - `src/billing/vat.ts` — modified `calculateVAT` (annotated with `@decision(DL-NNN)`)
+> - `src/billing/vat.test.ts` — added tests
+>
+> Next steps:
+> - `/dld-decide` — record another decision
+> - `/dld-audit` — check for drift between decisions and code

package/skills/dld-init/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: dld-init
+description: Bootstrap DLD (Decision-Linked Development) in a repository. Creates dld.config.yaml, the decisions/ directory, and INDEX.md. Run once per project.
+compatibility: Requires Node.js 20+ and git.
+metadata:
+  dld-kit-version: "1.0.0-rc.1"
+---
+<!-- Generated by dld-kit from templates/skills/dld-init/SKILL.md. Do not edit: updating the skills overwrites this file. -->
+
+# /dld-init — Bootstrap DLD
+
+You are initializing Decision-Linked Development (DLD) in this repository. This is an interactive setup process that runs once per project.
+
+## Interaction style
+
+Use the `AskUserQuestion` tool for all questions and prompts. This provides a structured input experience for the user rather than waiting for freeform replies.
+
+## Commands
+
+The commands below run the `dld` CLI bundled with the dld-common skill, and need Node.js 20+. `<skill-dir>` stands for the absolute path of this skill's directory. If `<skill-dir>/../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: `create-config`, `create-directories`, `create-empty-index`, `install-rule`.
+
+## Prerequisites
+
+- This must be a git repository
+- `dld.config.yaml` must NOT already exist at the repo root (if it does, tell the user DLD is already initialized and suggest the dld-status skill instead)
+
+Users who install dld-kit from npm can run `npx dld-kit init` in a terminal instead: it does steps 2–4 and 6 non-interactively and also installs the skills. This skill covers projects whose skills were installed another way.
+
+## Steps
+
+### 1. Ask about project structure
+
+Ask the user:
+
+> Is this a **flat** project (all decisions in one directory) or a **namespaced** project (decisions organized by component/domain, e.g., for a monorepo)?
+
+- **Flat** is the default and right for most projects
+- **Namespaced** is for monorepos or projects with distinct domains (billing, auth, etc.)
+
+If namespaced, ask for the initial namespace list. Suggest they can add more later.
+
+### 2. Create `dld.config.yaml`
+
+Run `create-config`:
+```bash
+node "<skill-dir>/../dld-common/scripts/dld.mjs" create-config <mode> [namespace1 namespace2 ...]
+```
+
+Example flat:
+```bash
+node "<skill-dir>/../dld-common/scripts/dld.mjs" create-config flat
+```
+
+Example namespaced:
+```bash
+node "<skill-dir>/../dld-common/scripts/dld.mjs" create-config namespaced billing auth shared
+```
+
+### 3. Create directory structure
+
+```bash
+node "<skill-dir>/../dld-common/scripts/dld.mjs" create-directories
+```
+
+This reads mode and namespaces from `dld.config.yaml` (created in step 2).
+
+### 4. Create initial INDEX.md
+
+```bash
+node "<skill-dir>/../dld-common/scripts/dld.mjs" create-empty-index
+```
+
+This reads mode from `dld.config.yaml`.
+
+### 5. Offer to create a practices manifest
+
+Ask the user:
+
+> Would you like to create a **development practices manifest**? This is an optional document (`decisions/PRACTICES.md`) that captures your project's development conventions (testing approach, code style, error handling patterns, etc.). The AI agent reads this when making and implementing decisions.
+>
+> You can skip this now and add it later at any time.
+
+If they accept, help them fill it out by asking about:
+- Testing practices (TDD? coverage targets? integration test requirements?)
+- Code style preferences (error handling patterns, validation approach)
+- Architecture conventions (dependency injection, repository pattern, etc.)
+
+If the repository already has application code, scan it first and suggest conventions you observe (e.g., "I see you're using Result types for error handling and Zod for validation — should I include those?"). This saves the user from having to recall everything from scratch.
+
+Write `decisions/PRACTICES.md` with their answers in simple markdown format:
+```markdown
+# Development Practices
+
+## Testing
+- ...
+
+## Code Style
+- ...
+
+## Architecture
+- ...
+```
+
+For namespaced projects, this is the root-level shared practices. Mention they can create namespace-specific practices later at `decisions/records/<namespace>/PRACTICES.md`.
+
+### 6. Install the always-on rule
+
+The rule tells the agent to look up `@decision` annotations before changing annotated code, in every session. Install it for the harness you are running in:
+
+```bash
+node "<skill-dir>/../dld-common/scripts/dld.mjs" install-rule --agent <harness>
+```
+
+`<harness>` is one of `claude` (Claude Code), `antigravity`, `codex`, `cursor`, `opencode` or `pi`; for another harness that reads `AGENTS.md`, such as Copilot CLI, use `codex`. If you are unsure which one you are, or the user says the team uses several agents, ask the user and pass them all, comma-separated (e.g. `--agent claude,codex`). The command decides where the rule goes (a rule file the harness loads, or a marked block in `AGENTS.md` or `CLAUDE.md`) and prints what it wrote; relay that to the user, including any warning.
+
+Do not write the rule into `CLAUDE.md` or `AGENTS.md` yourself.
+
+### 7. Suggest next steps
+
+Tell the user:
+
+> DLD is initialized. Here's what you can do next:
+
+If the repository already has application code:
+> - the dld-retrofit skill — generate initial decisions from your existing codebase
+> - Edit `decisions/PRACTICES.md` to refine your development practices (if created)
+
+If this is a new/empty project:
+> - the dld-decide skill — record your first decision
+> - the dld-plan skill — break down a feature into multiple decisions
+> - Edit `decisions/PRACTICES.md` to refine your development practices (if created)

package/skills/dld-lookup/SKILL.md

@@ -0,0 +1,76 @@
+---
+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: No external dependencies.
+metadata:
+  dld-kit-version: "1.0.0-rc.1"
+---
+<!-- Generated by dld-kit from templates/skills/dld-lookup/SKILL.md. Do not edit: updating the skills overwrites this file. -->
+
+# /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.
+
+## 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.
+
+Display the full decision record.
+
+### 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:
+
+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.