/change-init

name: change-init
description: Use when you want guided mining of git history, structured change-story clustering, or comprehensive rationale recovery before documenting. Optional for routine capture — team-boot writes lightweight ChDR drafts directly.
disable-model-invocation: true

change-init

What this skill does

Mine **git history** for **Change Decision Records (ChDRs)** — the *why* behind how the code came to be — and write them as draft records for human review.

A ChDR captures a decision that was *made in the past* and survives only in commits + linked issue trackers:

• Scan a window of `git log` for commit messages that reference an issue tracker (JIRA keys, GitHub/GitLab `#NNN`, MR `!NNN`, or issue URLs)
• Cluster commits sharing one issue key into a single **change story**
• Best-effort fetch the issue title/body (GitLab via MCP, GitHub via `gh`, else link-only) for requirement-level context
• Infer the **Decision** from the diff summary; record **Consequences** (reverts, follow-up fix chains — the negative knowledge almost never documented elsewhere)
• Write `ChDR-{NNN}.md` to `{REPO_ROOT}/.adlc/drafts/chdr/` with status **Discovered**
• Regenerate `{REPO_ROOT}/.adlc/drafts/chdr/chdr.md` index

**Key differences from the team-levelup family**:

| Skill | Source | Record | Question answered | |---|---|---|---| | `/team-init` | current code (what IS) | CDR (Context Directive) | what patterns are reusable | | `/team-levelup` | current session | CDR | what was learned this session | | `/change-init` (this skill) | **git history** (why it BECAME) | **ChDR** (Change Decision) | **why this code exists / what was tried and reverted** |

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/` (see `/change-publish`), and their index is injected at session start by `team-boot`.

When to use

> **Note**: Routine decision capture is handled by team-boot's continuous > capture mechanism, which writes lightweight drafts directly to > `.adlc/drafts/`. This skill is for **interactive deep-dive exploration** > — when you want guided trade-off analysis, multi-option comparison, or > structured decision facilitation before documenting.

• **Brownfield onboarding**: give an agent project memory without anyone writing docs
• **Before refactoring unfamiliar code**: surface Chesterton's fences — constraints that exist only in old commits + tickets
• **Recovering lost rationale**: when ADRs were never written but commits + issues exist
• **Post-incident learning**: revert/fix chains are first-class output

When NOT to use

• **Greenfield / no history**: nothing to mine
• **Documenting current patterns**: use `/team-init` (what IS)
• **Capturing this session's learnings**: use `/team-levelup`
• **Pending ChDRs already exist**: run `/change-clarify` to review them first

Process

User Input

$ARGUMENTS

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

**Examples of User Input**:

• `"--since 6months"` — limit the scan window
• `"--tracker gitlab"` — force tracker type (auto by default)
• `"--no-fetch"` — record issue links only, never fetch issue bodies
• `"--include-unlinked"` — also surface signal-rich unlinked commits (reverts, large cross-cutting diffs)
• `"src/payments"` — restrict to a path
• Empty input: scan last 500 commits across the whole repo, auto-detect tracker

Flags

• `--since DATE` / `--until DATE` / `--max-count N` (default 500): `git log` windowing
• `--path PATH`: restrict to a pathspec
• `--tracker gitlab|github|jira|auto` (default `auto`): issue-tracker integration
• `--no-fetch`: detect+record issue links only, never fetch bodies
• `--include-unlinked`: also cluster signal-rich unlinked commits (reverts, diffs touching ≥3 subsystems)
• `--limit N` (default 20): cap number of ChDRs generated
• `--resume`: resume from previous interrupted state

Role & Context

You are a **Context Archaeologist** recovering *why* the code is the way it is. Your job is **inference from evidence**, not invention:

• Every Decision claim MUST cite the commit SHA(s) and/or issue URL it was inferred from (provenance is non-negotiable — an unprovenanced inferred rationale is context poisoning, worse than no rationale)
• Mark confidence (HIGH/MEDIUM/LOW) on each Decision
• Record what you do NOT know explicitly ("Reason for choice unknown — commit message terse, no linked issue")
• Reverts and follow-up fix chains are the highest-value content: they are negative knowledge ("we tried X, it broke Y") documented almost nowhere else

Outline

1. **Validate Environment** (Phase 1): git repo, resolve paths, next ChDR number 2. **Scan Window** (Phase 2): `git log` with windowing 3. **Detect Issue Links** (Phase 3): regex over commit messages 4. **Cluster into Change Stories** (Phase 4): group commits by issue key 5. **Best-Effort Issue Fetch** (Phase 5): tracker content (degrade gracefully) 6. **Detect Revert/Fix Chains** (Phase 6): first-class negative knowledge 7. **Score & Prioritize** (Phase 7): subsystems touched, diff size, chains 8. **Generate ChDRs** (Phase 8): write drafts + index 9. **Output** (Phase 9): summary with linkage-rate metric

Execution Steps

Phase 1: Validate Environment

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

scripts/bash/setup-change-init.sh

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

**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