/change-clarify

name: change-clarify
description: Use when reviewing, accepting, rejecting, or deferring ChDRs mined by change-init, validating inferred decisions against their git and issue evidence before promotion to project memory.
disable-model-invocation: true

change-clarify

What this skill does

Review pending ChDRs (status **Discovered** or **Proposed**) and decide their fate: **Accepted**, **Rejected**, or **Deferred**.

This is the quality gate for Change Decision Records — the human checkpoint before inferred-from-history decisions are promoted to project memory and injected into future sessions by `team-boot`:

• Validate that inferred decisions are supported by cited commit SHAs / issue URLs (provenance — the context-poisoning circuit breaker)
• Check inferred-rationale confidence and flag low-confidence or unsupported claims
• Confirm issue-link validity and that fetched issue summaries are accurate (not pasted verbatim)
• Ensure Consequences (reverts/fix chains) are recorded where observed
• Update ChDR statuses in `{REPO_ROOT}/.adlc/drafts/chdr/ChDR-{NNN}.md`
• Regenerate `{REPO_ROOT}/.adlc/drafts/chdr/chdr.md` index

**This is an interactive command.** Present exactly one ChDR per interaction and wait for user input.

When to use

• **After `/change-init`**: validate history-mined ChDRs before promotion
• **Periodic review**: clean up stale pending ChDRs

When NOT to use

• **No pending ChDRs**: if no ChDRs have status Discovered/Proposed, there is nothing to clarify
• **Reviewing CDRs**: use `/team-levelup` (CDRs and ChDRs are distinct record types with separate gates)
• **Direct editing**: do not use this skill to bypass the review workflow

Process

User Input

$ARGUMENTS

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

**Examples of User Input**:

• `"ChDR-001 ChDR-003"` — focus on specific ChDRs
• `"all"` — clarify all pending ChDRs
• Empty input: clarify all ChDRs with status "Discovered" or "Proposed"

Flags

• `--all`: clarify all pending ChDRs (same as empty input)
• `--limit N`: limit to N clarifications per session (default: 5)

Role & Context

You are acting as a **Change Validator** reviewing inferred-from-history decisions. Unlike CDR clarification (which validates team-wide patterns), your focus is **evidence fidelity**:

• Was the Decision actually inferable from the cited commits, or did the agent invent it?
• Is the confidence level honest (a HIGH-confidence claim with a terse commit + no issue link is suspicious)?
• Are issue summaries accurate and not leaking sensitive detail verbatim?
• Are reverts/fix chains recorded where they exist (the highest-value content)?

ChDR Quality Checklist

Each ChDR should have:

• [ ] `### Context` explaining why the change happened (issue summary or commit messages)
• [ ] `### Decision` with inferred decision + confidence level
• [ ] **Every Decision claim cites a SHA or issue URL** (provenance — non-negotiable)
• [ ] `### Consequences` (reverts/fix chains, or explicit "None observed")
• [ ] `### Evidence` with concrete SHAs, files, and issue links
• [ ] Issue summaries are paraphrased, not raw paste (security)
• [ ] Status is accurate

Outline

1. **Load Pending ChDRs** (Phase 1): parse ChDR files with status Discovered/Proposed 2. **Pre-Validation** (Phase 2): skip ChDRs missing required sections or with unprovenanced Decision claims 3. **Gap Identification** (Phase 3): list clarification needs 4. **Sequential Clarification** (Phase 4): one ChDR per interaction 5. **Update ChDRs** (Phase 5): write status and clarification metadata after each decision 6. **Regenerate Index** (Phase 6): update `chdr.md` 7. **Summary** (Phase 7): present results

Execution Steps

Phase 1: Load Pending ChDRs

Run setup script:

scripts/bash/setup-change-clarify.sh

Read all `{REPO_ROOT}/.adlc/drafts/chdr/ChDR-*.md` files and filter:

• **Include**: `### Status: **Discovered**` or `### Status: **Proposed**`
• **Skip**: `### Status: **Accepted**`, `**Rejected**`, `**Published**`, `**Deprecated**`

**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`. 2. `CHDR_DRAFTS_DIR` — `REPO_ROOT/.adlc/drafts/chdr` 3. `PENDING_COUNT` — count files with Discovered/Proposed status.

If no pending ChDRs:

No pending ChDRs found.
Run /change-init to mine git history first.

Step 0: Detect Lightweight Draft Format

Check if the draft being reviewed uses the lightweight draft template (indicated by presence of `type`, `evidence`, `source`, `revisit-when` fields in frontmatter and `## Rejected Alternatives` / `## Reason` body sections without the full formal template sections).

If lightweight: 1. Read the draft's captured fields (Context, Decision, Rejected Alternatives, Reason) 2. Transform to full formal template:

• ADR: full MADR format with Decision Drivers, Considered Options, Pros/Cons, Constitution Alignment, Related ADRs
• PDR: full PDR format with Market Forces, Consequences, Alternatives Considered, Links
• ChDR: full ChDR format with Issue Links, Commits, Consequences, Evidence
• CDR: full CDR format with Context Type, Target Module, Descriptor, Evidence
• EVAL: full eval format with Error Analysis, Pass/Fail Examples, Implementation Notes

3. Enrich from session context (add details the lightweight draft may have omitted) 4. Present the enriched draft for review

If already full format, proceed with normal review.

Phase 2: Pre-Validation

For each pending ChDR, check required sections:

• `### Context`
• `### Decision` (with at least one confidence marker)
• `### Consequences`
• `### Evidence`
• **Provenance**: every non-trivial sentence in `### Decision` references a SHA (`\b[0-9a-f]{7,40}\b`) or URL (`https?://`)

Skip invalid ChDRs and report:

## Skipped ChDRs

| ChDR | Issue | Action |
|---|---|---|
| ChDR