# Creating Change Records > Creates or updates Quick or Standard change records, adds the required files, and refreshes what each claim must prove for an evidence-backed pull request. Use when starting or revising a change record. Do not use for a one-off throwaway script, or for work that belongs in an existing record rather than a new one. - Skill: `flyfission/creating-change-records` (Agent Skill) - Install (CLI): `npx skillmds@latest add flyfission/creating-change-records` - Raw SKILL.md: https://api.skillmd.com/api/skills/flyfission/creating-change-records/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: FlyFission (https://skillmd.com/u/flyfission) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/flyfission/creating-change-records --- # Creating Change Records ## Overview A change record keeps the whole story in Git, together: the scope, what the change must do, the plan, the trace from claim to evidence, the proof, and the release decision. Use the smallest record that still lets a doubting reviewer decide. ## Decision contract - **Claim checked:** the record carries every file its mode requires, with the required links, exit criteria, source-lineage notes, and plain status labels (`pass`, `fail`, `gap`, `deferred`, `not applicable`, `planned`) present and the internal links resolving. - **Artifact observed:** the mode from `risk.md` and the `templates/quick/` or `templates/standard/` templates -> a Quick record (`risk.md`, `proof.md`) or Standard record (`risk.md`, `basis.md`, `plan.md`, `trace.md`, `verification.md`, `ship.md`) plus the validator result. - **Decision affected:** block -- whether the packet is structurally complete and valid (`python tools/ng.py validate` pass/fail). - **Failure class:** incomplete-record (a missing file, broken internal link, or proof command absent). - **Next action:** add the missing file or link and rerun the validator; raise Quick to Standard or human review when proof cannot answer the reviewer. ## When to Use - You are starting a real AI-assisted change. - You are updating a record after the scope, proof, risk, or release posture changed. - You are preparing a pull request that needs evidence beyond the usual review notes. - A preview, a self-check, a handoff, a lesson from operation (OPEX), or a supplier trust check is in play and needs a record. ## When Not to Use - The work leaves no lasting artifact and no need for review. - The request is only to browse or explain existing docs. - You only need to pick the mode / grade the change's risk, not author the record yet -- use `rating-change-risk` instead. ## Inputs - The chosen mode from `risk.md` or from the risk-rating skill. - A questioning-attitude screen, when uncertainty, AI power, dependency trust, or release stakes are real. - Templates under `templates/quick/` or `templates/standard/`. - The files the change affects and the proof commands. - An existing record, if there is one. ## Process 1. Run `python tools/ng.py new --mode quick|standard`. 2. Say, in your reply, which required files the chosen mode needs, by name -- not only in the files themselves, so a reader without tool access still sees the list. Name only the set for the mode in play: Quick needs `risk.md` and `proof.md`; Standard needs `risk.md`, `basis.md`, `plan.md`, `trace.md`, `verification.md`, and `ship.md`. 3. Fill in only the parts of each file that help someone decide. 4. Add habit records (self-check, handoff, and the like) only when they change a decision or an action. 5. Link to the files affected, the tests, the reviews, the source-map rows, and the known gaps. 6. Keep status labels plain: `pass`, `fail`, `gap`, `deferred`, `not applicable`, or `planned`. 7. Run `python tools/ng.py validate .nuclear/changes/`. ## Outputs - Quick record: `risk.md`, `proof.md`. - Standard record: `risk.md`, `basis.md`, `plan.md`, `trace.md`, `verification.md`, `ship.md`. - Habit records such as `turnover.md`, `self-check.md`, `opex.md`, or `supplier-trust.md` when the stakes call for them. - The checker result. ## Verification - The required files exist. - The required links, exit criteria, and source-lineage notes are present. - The proof or verification file states the evidence status. - The links inside the record resolve. ## Escalation - Move from Quick to Standard when Quick proof cannot answer the reviewer's question. - Move to human review when a stronger written mode is in play. - Stop if the record turns into a long story with no links from claim to evidence. ## Common Rationalizations - "We will fill it in after the pull request." The evidence should shape the work, not dress it up afterward. - "Everything is obvious." If it matters to a future review, save the assumption and the path to the evidence. - "One big record is easier." One change per record keeps the review small enough to do well. ## Red Flags - A missing proof command or evidence link. - Claims that reach past what the tests or the review evidence cover. - Record files that repeat each other instead of linking. ## Prompt ```text Create or update a Nuclear-grade change record. Inputs: - slug: - mode: - scope: - affected files/assets: - questioned assumptions: - what the change must prove: - safety-habit (HPI) records started: Use the repo templates. Keep the record short. Lean on links, and point at evidence. Include the required links, the conditions for being done, and a note on where the ideas come from. Do not imply formal assurance or compliance. Return: - the required files for the chosen mode, named -- Quick: risk.md, proof.md; OR Standard: risk.md, basis.md, plan.md, trace.md, verification.md, ship.md (name only the set for the mode in play) - the filled-in content for those files ``` ## Source-lineage note This change-record skill is an original Git-native workflow. It draws on public configuration, lifecycle, assurance, secure-development, and release-readiness sources mapped in `docs/00-standards-foundation/source-map.md`. It does not create a certified quality assurance program.