Agent Change Ledger
Use this skill when an AI agent changes code and the result needs to be explainable,
reviewable, and easy to roll back. The output is an evidence-first change record,
not a generic code review.
Inputs
Accept any subset of:
- repository path or patch/diff
- change request or issue text
- files changed and their intended impact
- commands already run and their outputs
- test, lint, type-check, build, or deployment results
- reviewer identity and approval status
- rollback or revert procedure
Never request or record secrets, tokens, passwords, private keys, or full contents
of environment files. Redact them as [REDACTED].
Workflow
- State the intent in one sentence and list explicit acceptance criteria.
- Inventory the delta: files added, modified, deleted, generated artifacts,
schema/config changes, and public API changes. Distinguish observed facts from
claims.
- Map risk for each affected area: data loss, security, compatibility,
performance, operational, and migration risk. Mark unknowns explicitly.
- Build the validation matrix with command, scope, result, timestamp if known,
and evidence location. Never mark a check passed without output or a trusted
CI result.
- Apply review gates: required reviewer, unresolved comments, dependency or
migration approval, and deployment gate. A missing gate is
BLOCKED, not
PASS.
- Record rollback: exact revert action, stateful-data caveats, and the signal
that should trigger rollback.
- Emit the ledger in the format below and calculate the final status:
READY, BLOCKED, or NEEDS-EVIDENCE.
Output format
ledger_version: 1
change:
intent: "..."
acceptance_criteria: []
scope:
added: []
modified: []
deleted: []
public_interfaces: []
risk_register:
- area: security|data|compatibility|performance|operations|migration
level: low|medium|high|unknown
finding: "..."
mitigation: "..."
validation:
- command: "..."
result: pass|fail|not_run|unknown
evidence: "..."
review_gates:
- gate: "..."
status: pass|blocked|not_applicable|unknown
owner: "..."
rollback:
action: "..."
caveats: []
trigger: "..."
final_status: READY|BLOCKED|NEEDS-EVIDENCE
open_questions: []
Rules
- Prefer raw evidence and exact commands over prose assurances.
- Treat missing tests, missing review, and missing rollback details as explicit
gaps. Do not silently infer success.
- Keep the ledger small enough to review in one sitting; link to large logs rather
than embedding them.
- If the input is only a diff, produce
NEEDS-EVIDENCE until validation and
rollback information are supplied.
- Do not modify the repository unless the user separately asks for implementation.
1---2name: 6171-agent-change-ledger3description: Build an auditable evidence ledger for AI-assisted code changes: capture change intent, affected files, validation commands, review gates, rollback notes, and machine-readable release evidence from a diff or work session.4---56# Agent Change Ledger78Use this skill when an AI agent changes code and the result needs to be explainable,9reviewable, and easy to roll back. The output is an evidence-first change record,10not a generic code review.1112## Inputs1314Accept any subset of:1516- repository path or patch/diff17- change request or issue text18- files changed and their intended impact19- commands already run and their outputs20- test, lint, type-check, build, or deployment results21- reviewer identity and approval status22- rollback or revert procedure2324Never request or record secrets, tokens, passwords, private keys, or full contents25of environment files. Redact them as `[REDACTED]`.2627## Workflow28291. **State the intent** in one sentence and list explicit acceptance criteria.302. **Inventory the delta**: files added, modified, deleted, generated artifacts,31 schema/config changes, and public API changes. Distinguish observed facts from32 claims.333. **Map risk** for each affected area: data loss, security, compatibility,34 performance, operational, and migration risk. Mark unknowns explicitly.354. **Build the validation matrix** with command, scope, result, timestamp if known,36 and evidence location. Never mark a check passed without output or a trusted37 CI result.385. **Apply review gates**: required reviewer, unresolved comments, dependency or39 migration approval, and deployment gate. A missing gate is `BLOCKED`, not40 `PASS`.416. **Record rollback**: exact revert action, stateful-data caveats, and the signal42 that should trigger rollback.437. **Emit the ledger** in the format below and calculate the final status:44 `READY`, `BLOCKED`, or `NEEDS-EVIDENCE`.4546## Output format4748```yaml49ledger_version: 150change:51 intent: "..."52 acceptance_criteria: []53 scope:54 added: []55 modified: []56 deleted: []57 public_interfaces: []58risk_register:59 - area: security|data|compatibility|performance|operations|migration60 level: low|medium|high|unknown61 finding: "..."62 mitigation: "..."63validation:64 - command: "..."65 result: pass|fail|not_run|unknown66 evidence: "..."67review_gates:68 - gate: "..."69 status: pass|blocked|not_applicable|unknown70 owner: "..."71rollback:72 action: "..."73 caveats: []74 trigger: "..."75final_status: READY|BLOCKED|NEEDS-EVIDENCE76open_questions: []77```7879## Rules8081- Prefer raw evidence and exact commands over prose assurances.82- Treat missing tests, missing review, and missing rollback details as explicit83 gaps. Do not silently infer success.84- Keep the ledger small enough to review in one sitting; link to large logs rather85 than embedding them.86- If the input is only a diff, produce `NEEDS-EVIDENCE` until validation and87 rollback information are supplied.88- Do not modify the repository unless the user separately asks for implementation.
starchild-ai-agent