change-clarify
Review, accept, reject, or defer Change Decision Records (ChDRs) discovered by change-init. Interactive one-ChDR-at-a-time workflow that validates inferred decisions against their git/issue evidence before promotion to project memory.
tikalk · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add tikalk/adlc-team-skills --skill change-clarify技能说明
name: change-clarify description: Review, accept, reject, or defer Change Decision Records (ChDRs) discovered by change-init. Interactive one-ChDR-at-a-time workflow that validates inferred decisions against their git/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.mdindex
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
/levelup-clarify(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:
-
### Contextexplaining why the change happened (issue summary or commit messages) -
### Decisionwith inferred decision + confidence level - Every Decision claim cites a SHA or issue URL (provenance — non-negotiable)
-
### Consequences(reverts/fix chains, or explicit "None observed") -
### Evidencewith concrete SHAs, files, and issue links - Issue summaries are paraphrased, not raw paste (security)
- Status is accurate
Outline
- Load Pending ChDRs (Phase 1): parse ChDR files with status Discovered/Proposed
- Pre-Validation (Phase 2): skip ChDRs missing required sections or with unprovenanced Decision claims
- Gap Identification (Phase 3): list clarification needs
- Sequential Clarification (Phase 4): one ChDR per interaction
- Update ChDRs (Phase 5): write status and clarification metadata after each decision
- Regenerate Index (Phase 6): update
chdr.md - 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:
REPO_ROOT— walk up from cwd to find.adlc/, orgit rev-parse --show-toplevel.CHDR_DRAFTS_DIR—REPO_ROOT/.adlc/drafts/chdrPENDING_COUNT— count files with Discovered/Proposed status.
If no pending ChDRs:
No pending ChDRs found.
Run /change-init to mine git history first.
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
### Decisionreferences a SHA (\b[0-9a-f]{7,40}\b) or URL (https?://)
Skip invalid ChDRs and report:
## Skipped ChDRs
| ChDR | Issue | Action |
|---|---|---|
| ChDR-XXX | Decision claims lack SHA/URL provenance | Re-run /change-init or add evidence manually |
Phase 3: Gap Identification
Generate a gap report:
## ChDR Clarification Report
| ChDR | Title | Gap Type | Severity |
|---|---|---|---|
| ChDR-001 | [Title] | Low-confidence decision | MEDIUM |
| ChDR-002 | [Title] | Issue summary too verbose | LOW |
Gap types:
- Low-confidence decision: Decision marked LOW confidence — consider rejecting or deferring
- Unprovenanced claim: a Decision sentence without SHA/URL (should have been caught in Phase 2)
- Issue summary too verbose: pasted verbatim instead of paraphrased (security)
- Missing consequences: Consequences section empty but reverts observed in window
- Stale: cluster's commits later reverted (the decision was reversed — mark for rejection or status reversal)
Phase 4: Sequential Clarification
CRITICAL: Present exactly ONE ChDR per interaction. Do NOT:
- Present multiple ChDRs together
- Auto-select actions
- Procee