Change Init

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:

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-parse --is-inside-work-tree (exit 0 = true).
5. TD_CONFIGURED — true if TEAM_AI_DIRECTIVES resolves (used only to skip duplicate decisions already captured as CDRs).

If GIT_AVAILABLE is false:

Not a git repository — change-init has nothing to mine.
Run /team-init to scan current code instead.

Exit cleanly (do not create empty drafts).

Phase 2: Scan Window

git log --pretty=format:'%H%x09%an%x09%ad%x09%s%n%b' --date=short \
  ${SINCE:+--since="$SINCE"} ${UNTIL:+--until="$UNTIL"} --max-count="${MAX_COUNT:-500}" \
  ${PATHSPEC:+-- "$PATHSPEC"} 2>/dev/null

Capture per commit: SHA, author, date, subject, body, files touched (git show --stat --name-only), and subsystems (top-level dirs of touched files).

Phase 3: Detect Issue Links

Apply a combined regex to each commit message (subject + body):

Tracker type is auto-inferred from git remote get-url origin (gitlab.com / github.com / atlassian.net) and the link shapes found. --tracker overrides.

Commits with no detected link are unlinked; skipped unless --include-unlinked (then only those that are reverts or touch ≥3 subsystems are kept).