---
name: dld-adjust
description: Adjust or update existing decision records. Edits drafts freely, protects the prose of decisions already on the base branch per the project setting, and correctly interprets adjustment requests.
compatibility: Requires Node.js 20+ and git.
metadata:
  dld-kit-version: "1.0.0-rc.4"
---
<!-- Generated by dld-kit from templates/skills/dld-adjust/SKILL.md. Do not edit: updating the skills overwrites this file. -->

# /dld-adjust — Adjust a Decision

You are helping the developer adjust one or more existing decision records. Your job is to apply their requested changes accurately and minimally.

## Interaction style

Use the `AskUserQuestion` tool for all questions and prompts. This provides a structured input experience for the user.

## 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: `check-decision-edits`, `restore-decision-prose`, `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

This skill is typically invoked mid-session after `/dld-plan`, `/dld-decide`, or during `/dld-implement`, so the project context and decision content are likely already in your conversation context. Only read these if you don't already have the information:

1. `dld.config.yaml` — project structure (flat vs namespaced, decisions directory)
2. The target decision file(s) — decision records (`DL-*.md`) live in the `records/` subdirectory under the decisions directory

## Step 1: Identify the decision(s)

The user may specify decision IDs explicitly (e.g., `/dld-adjust DL-005`), but often they won't — this skill is typically used right after `/dld-plan`, `/dld-decide`, or during `/dld-implement`, so the decisions are already part of the current conversation context.

- **Explicit IDs provided** — use those directly.
- **No IDs provided** — infer which decision(s) the user is referring to from the conversation context. If decisions were recently created or discussed in this session, assume those are the target. If it's still ambiguous, ask using `AskUserQuestion`.

Find and read each decision file. If a decision ID is not found, report the error and continue with any remaining valid IDs.

## Step 2: Determine if confirmation is needed

Check where each decision stands:

```bash
node "<skill-dir>/../dld-common/scripts/dld.mjs" check-decision-edits DL-NNN [DL-NNN ...]
```

Each line ends with the decision's state.

### Drafts (`draft`)

The decision is not on the base branch yet, or is still `proposed` there. Edit freely, whatever its status. No confirmation needed.

### On the base branch (`integrated` or `edited`)

The frontmatter (`status`, `references`, `amends`, `supersedes`, `tags`, `title`) can always be updated, except `id` and `timestamp`, which never change. For the prose (the body below the frontmatter), follow `decision_edits` in `dld.config.yaml` (default `block`):

- `block`: don't edit the prose, even though the user asked. Tell them this project keeps the prose of decisions on the base branch as written, and offer to record the change as a new decision that amends or supersedes this one (`/dld-decide`). Mention that `decision_edits: ask` in `dld.config.yaml` would allow edits after confirmation. If the request also changes frontmatter fields, make only those changes; then skip to step 6.
- `ask`: use `AskUserQuestion` to present options:
  1. **Edit anyway** — modify the decision's prose directly
  2. **Amend or supersede instead** — record a new decision via `/dld-decide`
  3. **Cancel** — do nothing

  If the user chooses a new decision, direct them to `/dld-decide` and stop. If they cancel, stop. Only edit if they choose to edit anyway.
- `allow`: edit, and mention in your summary that the decision was already on the base branch.

### Deleted (`deleted`)

The decision is on the base branch but its file is gone on this branch. Tell the user and stop.

If the command can't find the base branch, tell the user, and ask for confirmation before editing the prose of any decision that is not `proposed`.

## Step 3: Collect the adjustment request

If the user provided the adjustment alongside the skill invocation (e.g., `/dld-adjust DL-005 remove the mention of Java records`), use that directly.

Otherwise, ask what changes they want to make.

Read the current decision content so you understand the full context of what you are working with.

## Step 4: Apply the changes

### CRITICAL — How to interpret adjustment requests

AI agents consistently misinterpret adjustment requests. Follow these rules exactly:

**"Remove X" means DELETE the content about X.**
Do NOT replace it with "We decided not to use X" or "We chose against X" or any other negative phrasing. Simply remove the sentences, bullet points, or paragraphs that mention X. The goal is a clean decision record that reads as if X was never discussed.

**"Change X to Y" means REPLACE the content.**
Find where X is described and replace it with Y. Do not add explanatory text about the change.

**"Add X" means INSERT new content.**
Add the new content in the appropriate section. Do not add meta-commentary about it being an addition.

**General principle:** The decision record should always read as a clean, coherent document. Never add editorial notes like "Updated on...", "Previously we...", "This was changed from...", or "We decided against...". The record captures the current state of the decision, not a changelog of edits.

**Examples of WRONG vs RIGHT:**

User says: *"Remove the mention of Java records from DL-005"*

- WRONG: Replacing "We will use Java records for DTOs" with "We decided not to use Java records for DTOs"
- RIGHT: Deleting the sentence "We will use Java records for DTOs" entirely (and any related sentences about Java records)

User says: *"Change the retry count from 3 to 5"*

- WRONG: Adding "Originally 3 retries, changed to 5 retries because..."
- RIGHT: Replacing "3 retries" with "5 retries" wherever it appears in the decision

User says: *"Remove the part about caching"*

- WRONG: "We considered caching but decided it is not relevant to this decision"
- RIGHT: Delete all sentences and paragraphs about caching. Adjust surrounding text so the document flows naturally.

### Applying edits

1. Read the full decision file
2. Apply the requested changes to the markdown body (and frontmatter fields like title or tags if affected)
3. Write the updated file
4. Show the user a brief summary of what changed

If multiple decisions are being adjusted, process them one at a time.

## Step 5: Check edits to decisions on the base branch

```bash
node "<skill-dir>/../dld-common/scripts/dld.mjs" check-decision-edits --uncommitted
```

This lists decisions that are already on the base branch and whose prose (the body below the frontmatter), `id` or `timestamp` has uncommitted changes, or that were deleted. Drafts (decisions not on the base branch yet, or still `proposed` there), changes to other frontmatter fields and edits already committed are never listed. If it prints nothing, continue. If a listed edit isn't yours (the user made it by hand), leave it alone and mention it. Edits the user approved in step 2 count as kept; don't ask about them again.

Otherwise follow `decision_edits` in `dld.config.yaml` (default `block`; the command then exits 3):

- `block`: put the prose back with `node "<skill-dir>/../dld-common/scripts/dld.mjs" restore-decision-prose --uncommitted DL-NNN ...`, which also restores `id` and `timestamp` and keeps other frontmatter changes. If the change is still needed, record it as a new decision that amends or supersedes the old one (`/dld-decide`), and tell the user.
- `ask`: for each listed decision, ask the user with `AskUserQuestion` whether to keep the edit. Restore the ones they don't keep.
- `allow`: keep the edits and list them in your report.

If the command can't find the base branch, tell the user and continue.

## Step 6: Regenerate INDEX.md

If any decision titles or metadata changed:

```bash
node "<skill-dir>/../dld-common/scripts/dld.mjs" regenerate-index
```

## Step 7: Suggest next steps

> Adjusted **DL-NNN**: [brief description of what changed]
>
> Next steps:
> - `/dld-lookup DL-NNN` — review the updated decision
> - `/dld-implement DL-NNN` — implement if the decision is proposed
> - `/dld-snapshot` — regenerate overview docs to reflect the update