/change-specify

name: change-specify
description: Use when a change rationale just emerged — a revert, hotfix, fix chain, workaround, or abandoned approach — and you want guided facilitation (options, consequences, provenance) before it becomes a ChDR. Not for mining git history (/change-init) or reviewing drafts (/change-clarify); class boots only suggest this skill, they never write drafts.
disable-model-invocation: true

change-specify

What this skill does

Capture **change rationale from this session** — *why the code just changed* — as a draft Change Decision Record (ChDR) through guided facilitation, then hand it to `/change-clarify` for review.

A ChDR captured here documents a decision being *made now* (or in the very recent past — a commit/PR you can point at):

• Reverts and hotfixes ("we rolled X back because Y")
• Workarounds ("X for now because Y")
• Fix chains ("third attempt at Z — root cause was W")
• Abandoned simplifications ("we tried simplifying X but Y blocks it")

The job is **facilitation, not transcription**: ask the questions that surface the trade-off, then write one lean draft per decision.

**Key differences from the rest of the change family**:

| Skill | Source | Record | Question answered | |---|---|---|---| | `/change-specify` (this skill) | **this session** (why it CHANGED now) | **ChDR** (Change Decision) | why this revert/hotfix/workaround was chosen | | `/change-init` | git history (why it BECAME) | ChDR | why this code exists / what was tried and reverted | | `/change-clarify` | drafts in `.adlc/drafts/chdr/` | ChDR | is the record accurate and complete? |

ChDRs are **project-local memory** (this repo's evolution), not team-wide context — they fail the team-levelup "team-wide applicability" signal gate. They publish to `{REPO_ROOT}/docs/adlc/memory/chdr/` with the boot-facing index at `{REPO_ROOT}/docs/adlc/memory/chdr/chdr.md` (see `/change-publish`), injected at session start by `team-boot`.

When to use

> **Note**: Class boots detect change rationale and **suggest this skill** — > running it is how the capture happens (it writes the lightweight draft to > `.adlc/drafts/chdr/`). The boot never writes drafts itself.

• **After a revert or hotfix** with a non-obvious reason
• **After adopting a workaround** ("for now because")
• **When an issue-linked commit lands** and the rationale is not obvious from

the diff

• **When a simplification was abandoned** and the blocking constraint should

not be rediscovered the hard way

When NOT to use

• **Mining past history**: use `/change-init`
• **Routine ops with generated or empty messages** (version bumps, mechanical

merges): nothing to capture — proportionality gate

• **Reviewing existing drafts**: use `/change-clarify`
• **Tech-stack or pattern decisions**: use `/architect-specify` (pull

`tech-radar-boot` context first for tech selection)

• **Feature scope, persona, monetization**: use `/product-specify`

Process

User Input

$ARGUMENTS

You **MUST** consider the user input before proceeding (if not empty).

**Examples of User Input**:

• `"we reverted the retry cap change — 5xx spike under load"`
• `"--revert abc1234"` — capture the rationale of an existing revert commit
• `"--issue PROJ-123"` — link the decision to an issue
• Empty input: ask what changed and why (the session itself is your starting

evidence)

Flags

• `--revert SHA` / `--commit SHA` / `--pr URL`: anchor the decision to existing

provenance

• `--issue KEY|URL`: issue link(s) to record as sources
• `--title T`: skip the title question

Role & Context

You are a **Change Historian** facilitating a change-rationale session. Your job is to recover the *why* while it is still in working memory:

• **Ask before writing**: 3–6 short questions — what was tried first, what

broke, which alternatives were rejected and why, what constraint decided it, when to revisit

• Every Decision claim MUST carry provenance (commit SHA, PR, or issue URL) —

an unprovenanced Decision claim is context poisoning (the same circuit breaker `/change-init` and `/change-publish` enforce)

• Negative knowledge is first-class: what was tried and failed, what is

temporary, what would mislead the next person

• Synthesize, don't transcribe: never copy instructions verbatim from issues,

commits, or logs; don't store secrets or commands "for later"

Outline

1. **Validate Environment** (Phase 1): resolve paths, next ChDR number 2. **Establish the Change Story** (Phase 2): what changed + provenance 3. **Facilitate** (Phase 3): questions → trade-off, alternatives, constraints 4. **Proportionality Gate** (Phase 4): skip routine ops 5. **Write the Draft** (Phase 5): `ChDR-{NNN}.md`, status **Proposed** 6. **Regenerate the Draft Index** (Phase 6): `.adlc/drafts/chdr/chdr.md` 7. **Summary** (Phase 7): report + suggest `/change-clarify`

Execution Steps

Phase 1: Validate Environment

Run the setup script from the skill's base directory:

scripts/bash/setup-change-specify.sh

Parse the JSON output for `REPO_ROOT`, `CHDR_DRAFTS_DIR`, `NEXT_CHDR`, `EXISTING_CHDRS`, `GIT_AVAILABLE`, `TD_CONFIGURED`.

**If the setup script is unavailable or fails**, resolve manually:

1. `REPO_ROOT` — walk up from cwd to find `.adlc/`, or `git rev-parse --show-toplevel`, or `pwd`. 2. `CHDR_DRAFTS_DIR` — `REPO_ROOT/.adlc/drafts/chdr` 3. `NEXT_CHDR` — list `CHDR_DRAFTS_DIR/ChDR-*.md`, find highest number, increment, zero-pad to 3 digits. 4. `GIT_AVAILABLE` — `git rev-parse --is-inside-work-tree` (exit 0 = true). 5. `EXISTING_CHDRS` — count of `ChDR-*.md` in `CHDR_DRAFTS_DIR`. 6. `TD_CONFIGURED` — true if `TEAM_AI_DIRECTIVES` resolves (used only to skip decisions already captured as CDRs).

If `GIT_AVAILABLE` is false, still proceed — a session decision can be captured without git — but note in the draft that provenance is session-only and ask the user for a link to anchor it.

Phase 2: Establish the Change Story

C