| name | doc-chg-autopilot |
| description | Drive a Change Management record end-to-end with minimal prompts - detect the change, classify the level, draft the CHG, assess cross-layer cascade, and prep the entry gate. Use to author or batch CHGs hands-off. |
| metadata | {"tags":["sdd-workflow","change-management","automation-workflow"],"custom_fields":{"artifact_type":"CHG","skill_category":"automation-workflow","version":"0.24.0","framework_spec_version":"0.40.0","last_updated":"2026-06-12","adapts":["section_toggles","active_layers","audit_threshold","glossary","review_mode"]}} |
doc-chg-autopilot
Purpose
Automated CHG pipeline. From a change request — a diff, an incident, a
prompt, or an upstream artifact edit — it detects the change, classifies the
level, drafts a complete CHG record, traces the cross-layer cascade, registers
it, and prepares the entry gate for approval — for one change or a batch.
CHG is NOT a lifecycle layer in the BRD..IPLAN sense: no template chain,
no readiness score. The pipeline closes on gate approval, not a numeric
score. For team-mode dispatch purposes the CHG layer is addressed as
09_CHG (the layer-id slot occupied by the change-management overlay).
This autopilot deliberately carries no ## Model precheck step. The
per-layer model recommendation (MODEL-PRECHECK-ROLLOUT) applies to the eight
lifecycle-layer autopilots (BRD..IPLAN); CHG is a governance overlay with no
model.per_layer.CHG entry, so there is nothing to precheck. The conformance
suite (tests/conformance/platforms/test_model_precheck.py) asserts the
precheck on exactly those eight — CHG's absence is intentional, not a gap.
Skill Dependencies
| Skill | Role |
|---|
../doc-chg/SKILL.md | CHG structure, classification, and routing rules |
../doc-chg-audit/SKILL.md | gate-readiness check (pass/fail + fix list) |
../doc-chg-fixer/SKILL.md | applies fixes from the audit report |
../gate-check/SKILL.md | runs the formal gate (C3/Emergency) + approval form |
../review-team/SKILL.md | team-mode dispatcher (parallel persona subagent fan-out) |
Input Contract
Accepts: a target CHG-NN/path; a diff or list of edited artifacts; an incident
reference; or a free-text change description. Optional: max fix iterations
(default 3), batch list. With no explicit input, treat the request as a change
description and infer the source.
Smart Document Detection
For each target, check whether the CHG already exists in the change registry
(CHG-00_index.md):
- Missing → generate mode (draft a new CHG record).
- Exists → review & fix mode (audit, then fix if it fails gate-readiness).
Infer the change source (upstream/midstream/design/execution/external/
feedback) and level (C1/C2/C3/Emergency) from the changed artifacts and the
trigger.
Workflow
MANDATORY — DO THIS FIRST. Your first and only action when
review_mode: team (the framework default) is to invoke the saga
driver via the Bash tool. You MUST NOT dispatch Task subagents
directly, MUST NOT call doc-chg/doc-chg-audit/doc-chg-fixer
directly via SlashCommand or otherwise, and MUST NOT generate
the CHG in-session. The driver is the sole orchestration mechanism for
the create-review-revise loop. Bypassing it produces a CHG without
a saga.json journal — the same failure mode the BRD/PRD/EARS slim-downs
closed out at their respective layers.
Saga-driven generation loop (review_mode: team)
Step 1 — Invoke the driver. Period. The harness sets PREV_OUTPUT,
ARTIFACT_ID, ARTIFACT_PATH env vars before invoking this SKILL.
Your VERY FIRST tool call MUST be the Bash tool, running exactly:
python3 "${CLAUDE_PLUGIN_ROOT}/tools/saga_driver.py" \
--layer 09_CHG \
--artifact-path "${ARTIFACT_PATH}"
Use a generous timeout (≥1800s). Do not pre-analyze the input. Do not
read the seed. Do not classify level/source. The driver and its
dispatched subprocesses (/aidoc-flow:doc-chg for draft,
/aidoc-flow:doc-chg-audit for review, /aidoc-flow:doc-chg-fixer
for fixer) handle all of that. The driver enforces the state machine
preemptively per
${CLAUDE_PLUGIN_ROOT}/framework/governance/REVIEW_SAGA.md; this
SKILL's job is to invoke it and report.
Step 2 — After the driver returns, report. Read
.aidoc/review/09_CHG/${ARTIFACT_ID}/saga.json. Final status MUST be
one of CLOSED (PASS, gate_ready: true), ESCALATED (terminal
FAIL), or PARTIAL_TIMEOUT (soft-deadline; resumable). Print the
status, the gate_ready boolean from verdict.json if present, and a
1-line summary.
Step 3 — Index update (only on CLOSED). Add a row to
CHG-00_index.md referencing the new CHG.
Step 4 — Gate prep (only on CLOSED). C1 commits directly; C2
routes to peer review; C3/Emergency hand off to
../gate-check/SKILL.md to run the formal/post-hoc gate and
complete GATE_APPROVAL_FORM. For Emergency, schedule the post-mortem
(${CLAUDE_PLUGIN_ROOT}/framework/governance/chg/templates/POST_MORTEM-TEMPLATE.md)
within 48h of the fix deploy.
That is the entire workflow in team mode. If you find yourself
doing anything else here — drafting prose, dispatching Task subagents,
invoking other slash commands — STOP, recognize that you are
bypassing the driver, and invoke the Bash command above instead.
Linear Pipeline (review_mode: single_pass)
Unchanged legacy behaviour — used when the profile says so, when Task
subagent dispatch is unavailable, or at write-time (on_author) where
cost is the primary concern.
- Input analysis — classify the input (diff / incident / prompt / upstream
edit), locate the touched artifacts, and decide generate vs review-and-fix.
- Type & scope — classify the change level and source per
../doc-chg/SKILL.md; select the entry gate (GATE-01/03/06/08/CODE, or
GATE-SPEC for a framework/-spec change — set semver_impact, ≥C2);
reserve the next CHG-NN (or CHG-EMG-YYYYMMDD-HHMM for Emergency).
- Generation — populate
${CLAUDE_PLUGIN_ROOT}/framework/governance/chg/CHG-TEMPLATE.yaml:
metadata, change_control, description (what/why/trigger), implementation,
verification. Impact assessment is mandatory — trace the cascade along
BRD→PRD→EARS→BDD→ADR→SPEC→TDD→IPLAN→Code (downstream for upstream/external,
bubble-up for feedback, lateral for midstream) and list every affected
artifact. Add rollback_plan (C2/C3), gate_approval (C3),
emergency_change (Emergency).
- Validation — run
../doc-chg-audit/SKILL.md from scratch in
single_pass mode.
- Audit ↔ fix cycle — while the audit FAILs and iterations < max: run
../doc-chg-fixer/SKILL.md in single_pass mode, then re-audit. On pass,
update CHG-00_index.md; on exhausting iterations, flag for manual review.
- Gate prep — C1 commits directly; C2 routes to peer review; C3/Emergency
hand off to
../gate-check/SKILL.md to run the formal/post-hoc gate and
complete GATE_APPROVAL_FORM. For Emergency, schedule the post-mortem
(${CLAUDE_PLUGIN_ROOT}/framework/governance/chg/templates/POST_MORTEM-TEMPLATE.md) within 48h of
the fix deploy.
Execution Modes
- Single — one CHG (generate or review-and-fix).
- Batch — multiple changes, processed in chunks of 3 to bound context;
generate upstream-source CHGs before the downstream ones that depend on them.
- Dry-run — report the planned classification, source, entry gate, and
cascade list without writing files.
Quality Gates
- A CHG is not "done" until the audit passes (0 blocking findings) and the
required approval is obtained: C1 self, C2 peer review, C3/Emergency gate via
../gate-check/SKILL.md. There is no numeric readiness score.
- The change registry is updated only after a CHG passes the audit.
- Fresh audit every cycle — no cached results.
Error Handling
| Situation | Action |
|---|
| Source ambiguous | infer from touched layers; record the assumption in the CHG |
| Cascade incomplete (E003) | re-trace the chain before drafting impact assessment |
| Entry gate mismatch (E002) | re-route per the source table; correct entry_gate |
| Max iterations reached, still failing | write reports, flag for manual review, continue batch |
| Emergency post-mortem overdue | block sign-off; escalate; keep post_mortem_completed: false |
Adaptation
Before applying defaults, read the project adaptation profile
(.aidoc/profile.yaml) and apply it in both the generation and the internal
audit/fix phases. Honor section_toggles, active_layers, audit_threshold
(raise-only — stricter only), glossary, and review_mode (select team to
invoke the saga driver per §Saga-driven generation loop; single_pass to run
the linear pipeline). Ignore any unknown or out-of-surface key; absent a
profile, use framework defaults (team at gates / single_pass at write-time).
Authority: ${CLAUDE_PLUGIN_ROOT}/framework/governance/ADAPTATION.md.
Related Resources
- Create:
../doc-chg/SKILL.md · Audit: ../doc-chg-audit/SKILL.md · Fix:
../doc-chg-fixer/SKILL.md · Gate: ../gate-check/SKILL.md
- Authority:
${CLAUDE_PLUGIN_ROOT}/framework/governance/chg/CHG-TEMPLATE.yaml,
${CLAUDE_PLUGIN_ROOT}/framework/governance/chg/README.md,
${CLAUDE_PLUGIN_ROOT}/framework/governance/chg/CHG-00_index.TEMPLATE.md,
${CLAUDE_PLUGIN_ROOT}/framework/governance/chg/gates/,
${CLAUDE_PLUGIN_ROOT}/framework/governance/AUTHORING_STYLE.md
