FlyFission/nuclear-grade-context-engineering

# Breaking Down the Work

## Overview

A work breakdown (WBS) splits one deliverable into smaller pieces someone can own, with no gaps and no overlaps, plus a dictionary that defines every piece. "Product-first" means the pieces are the things you build (nouns), not the actions you take (verbs). The work breakdown is the spine that estimates, folders, ownership, and traceability hang from.

Three things can wreck it. Under-coverage: some scope is orphaned and no one owns it. Over-coverage: invented or gold-plated scope that no one asked for. And a third drift where verbs pose as the backbone and hide products that are actually missing. This skill holds two rules: the 100% rule (the pieces add up to exactly the whole, no more and no less) and no overlaps. It also forces a dictionary entry for every piece. That way the breakdown can be reviewed before any folder or line of code exists.

## Decision contract

- **Claim checked:** product-first children cover exactly the parent (100% rule), no two siblings overlap, every outline number has a filled dictionary entry.
- **Artifact observed:** the one-line deliverable, mission anchor, and `templates/standard/wbs.md` -> an outline-numbered table, per-piece dictionary, and handoff to folders and each leaf's `plan.md`.
- **Decision affected:** block -- plan-ready vs not: do the children sum to 100% with no gaps and no overlaps (MECE).
- **Failure class:** non-mece-breakdown (orphaned scope, invented scope, or overlap with no stated gap).

# Briefing an Agent

## Overview

A context pack gives an agent or a reviewer the right focused information, and nothing extra. It states the role, the mode, the question to decide, the goal, the files affected, the evidence to produce, the approvals, the actions that are off limits, where the ideas came from, the most important next action, and the state of the work so far.

A good brief is how you supply competence and clarity so the agent can decide well rather than be micromanaged: name what good looks like, and state the decision rights — what it may decide at the edge and what it must escalate. Authority that outruns the clarity in the brief is the setup for a confident, wrong action.

## Decision contract

- **Claim checked:** the agent can answer what it may do, what must stay true, what evidence it owes, and when to stop -- its power over files, commands, network, credentials, approvals, and release is bounded no wider than the brief's clarity, with the goal anchor and forbidden actions stated.
- **Artifact observed:** the change-record path, its mode, the assigned role, and `context-packs.md` -> a context-pack with role, goal anchor, scoped files/commands, phase, authority bounds, stop conditions, and the next action.
- **Decision affected:** block -- whether the briefed agent may start, and the authority bounds it may act within.
- **Failure class:** boundary-overreach (authority wider than the brief's clarity, or forbidden actions and allowed files unstated).

# Checking Legal and Safety Wording

## Overview

This skill keeps two things apart: what the MIT license lets people do, and what the repo proves. People may use the repo. But using it does not create formal verification and validation, compliance, certification, safety, security, or fitness for regulated use.

## Decision contract

- **Claim checked:** public text stays inside the assurance boundary -- "you may use it" kept apart from "it is proven fit", banned claim phrases only in negative or disclaimer sentences, and `python tools/ng.py doctor .` passes.
- **Artifact observed:** the changed public text against `LICENSE`, `DISCLAIMER.md`, `SECURITY.md`, and `compliance-boundaries.md` -> bounded wording, updated docs/templates, and the scan results or list of gaps.
- **Decision affected:** block -- whether public text stays inside the assurance boundary; an overreaching license/safety/compliance claim blocks until reworded.
- **Failure class:** assurance-overreach (public copy promising safe, secure, compliant, approved, or certified results the repo has not proven).
- **Next action:** reword to evidence-tied wording before release; requests for legal advice or regulated-use approval escalate to a qualified professional.

# Checking Release Readiness

## Overview

Release readiness is a careful, audited decision you write down. It is not a mood. It ties seven things together before a candidate becomes the accepted version: the baseline (the version everyone agreed is correct), the evidence status, the leftover risk, the rollback plan, the monitoring plan, the handoff, and the release decision itself.

## Decision contract

- **Claim checked:** the candidate has evidence, visible custody and coupling, rollback, monitoring, and residual risk that is accepted or made a blocker; for trust-bearing work the declared coupling profile meets the consequence-specific minimum.
- **Artifact observed:** `verification.md`/`trace.md` statuses and CI status -> the decision recorded in `ship.md`.
- **Decision affected:** block -- the `ship.md` ship/block/defer/ship-with-risk release decision.
- **Failure class:** unevidenced-or-unsafe-release (a gap or missing rollback treated as shippable).
- **Next action:** block the release; record the gap, its owner, and a recheck trigger.

# Checking Source Claims

## Overview

"Source lineage" means showing where an idea came from. Honest lineage keeps public claims clean. It links an idea to a real public source. At the same time, it keeps the repo from sounding like it formally meets that source's rules.

## Decision contract

- **Claim checked:** every cited source is public and in the source map or marked "public URL needed", and each reference reads as influence or idea lineage rather than compliance, certification, or formal assurance.
- **Artifact observed:** the changed public text against `source-map.md`, `source-to-concept-crosswalk.md`, and `compliance-boundaries.md` -> narrowed wording and updated source-map or crosswalk rows.
- **Decision affected:** warn -- whether public/source wording is narrowed to honest influence or idea lineage rather than a compliance claim.
- **Failure class:** overstated-lineage (an unconfirmed source cited as direct lineage, or a compliance/approval claim outside a disclaimer).
- **Next action:** downgrade the source to "public URL needed" or reword to influence; wording affecting regulated, customer, or investor trust escalates.

# Checking What a Change Affects

## Overview

An impact screen asks a simple question. When a controlled item changes, what else does that change leave out of date? You look downstream for ripple effects before they surprise you.

## Decision contract

- **Claim checked:** every artifact a controlled change could leave stale -- docs, tests, checkers, skills, commands, templates, prompts, releases, saved versions, and runtime blast radius (schema/state migration, API consumers, backward-compatibility, rollback-of-state) -- has one named action with evidence, and no stale surface is quietly accepted.
- **Artifact observed:** the controlled-item list, `risk.md`, `basis.md`, `plan.md`, the diff, and `change-impact.md` -> `change-impact.md` with per-item actions, re-check triggers, and required follow-ups.
- **Decision affected:** block -- per affected item, update / leave alone / defer / block; blockers carry into `ship.md`.
- **Failure class:** missed-ripple (a stale doc, test, checker, or runtime contract quietly accepted).
- **Next action:** assign each stale surface an action with an owner and trigger; escalate when it touches outside trust, security, or the release.

# Choosing What to Control

## Overview

Controlled items are the parts of a system whose approved version matters. They matter to trust, to review, to being able to repeat a result, to what an agent may do, or to a release. This skill keeps the approved version of those items under control. Engineers call that keeping the approved version under control, or configuration management (CM).

## Decision contract

- **Claim checked:** every item whose approved state affects trust, agent power, the release, repeatability, or public understanding is named -- with owner, current and intended state, an evidence link or stated gap, and a re-check trigger -- and nothing in scope is silently left uncontrolled.
- **Artifact observed:** the request/diff/record and `controlled-items.md` (plus any `risk.md`, `basis.md`, `plan.md`) -> the controlled-item list with owners, states, triggers, and named gaps.
- **Decision affected:** warn -- which code, prompts, models, dependencies, docs, and releases become controlled items (feeds `change-impact.md` and the baseline).
- **Failure class:** uncontrolled-item (drift in an unlisted prompt, doc, or agent-power state left untracked).
- **Next action:** name the item, owner, and re-check trigger; escalate when drift could hit users, security, releases, or agent power.

# Closing Stale Packets

## Overview

A change packet that is started and then abandoned is a quiet integrity problem. It looks like work in progress, but no one owns it, its claims were never proven, and a reader cannot tell whether the change shipped, was dropped, or is still pending. `ng status` now surfaces these: a `scaffold` packet is an untouched draft still carrying the placeholder marker; an `invalid` packet fails validation for another reason. This skill turns that signal into a decision. Every stale packet must reach one honest terminal state: completed (filled and validating), closed (deliberately abandoned with a recorded reason), or deleted (never a real change). The forbidden state is the one most packets drift into: half-done and silent, where a green-looking directory hides an unproven claim. Closing a packet with a written rationale is a first-class successful outcome, not a failure to ship.

## Decision contract

- **Claim checked:** every stale packet reached one honest terminal state -- completed and validating, closed with a recorded reason and decider, or deleted as a genuinely empty scaffold -- none left half-done and silent.
- **Artifact observed:** `ng status .`/`validate` output and the packet against its originating issue/PR/anchor -> a `NUCLEAR-GRADE-CLOSED:` rationale line and an `ng status .` where every packet is `ok` or `closed`.
- **Decision affected:** block -- bring the stale packet to a terminal state so `ng status` reports ok/closed, not scaffold/invalid.
- **Failure class:** silent-stale-packet (a half-done packet hiding an unproven claim, or a faked pass by deleting the marker).
- **Next action:** complete, close-with-reason, or delete; escalate to the owner before deleting any packet whose change is not confirmed dead.

# 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.

# Deciding Who Decides

## Overview

Authority should sit where the policy, evidence, competence, and effective ability to intervene support it, not automatically at the top or with the actor holding the tool. This skill creates an evidence-conditioned authority record for one bounded decision episode. It separates prepare, recommend, verify, validate, verdict, accept, apply, reopen, and close rights; links evidentiary rights to exact Evidence IDs; names the authority that may assemble each right's basis; preserves unknown and disputed states; and names transfer or blocking triggers. It does not infer authorization from technical capability, repository activity, fluency, or nominal human presence.

## Decision contract

- **Claim checked:** each decision right is assigned under an explicit local policy to a named actor; each right's declared basis and basis authority are visible; required Evidence IDs and their custody profile are visible; unresolved evidence cannot silently clear agent application; and transfer/reopen/close triggers are concrete.
- **Artifact observed:** the bounded action; `verification.md` Evidence IDs, coded source states, intended-use/V&V status, and coupling profile; declared policy identity, authority, custody, digest, and validity; effective intervention capability; and any existing human gate -> `decision-authority.md` plus a declaration-relative structural result.
- **Decision affected:** block -- does the declared record structurally permit agent application, require authority transfer or separate/dual control, or remain blocked/prohibited/indeterminate?
- **Failure class:** misplaced-authority or unsupported-basis (capability treated as authorization, unresolved/self-check evidence clearing agent action, prohibited role overlap, stale basis, or skipped gate).
- **Next action:** record raw observations, derive the declaration-relative result, and transfer or block before side effects when the basis or authority is unresolved.

# Declaring Intent

## Overview

Before a critical action, say what you intend to do and the reasoning behind it, then act unless someone stops you. The value is that a reviewer can challenge the thinking before the action happens, not the wreckage after. The declaration also forces the actor to make the "why" and the "how will I know" explicit. For an agent, the stated intent is a proposal to be reviewed, never evidence that the agent actually understood.

## Decision contract

- **Claim checked:** the declared intent names a falsifying signal (not just success), carries concrete abort criteria and a checked rollback, and the preconditions are proven rather than assumed before the action runs.
- **Artifact observed:** the intended action and target, the reasoning and precondition evidence, the expected result, and the abort/rollback criteria -> an intent declaration or `intent.md` (action, reasoning, expected result, abort, rollback, decision rights, backup) and the actual-vs-expected result.
- **Decision affected:** block -- whether a reviewer clears the critical or irreversible action before it runs, given expected result, abort criteria, and rollback.
- **Failure class:** unfalsifiable-intent (a stated goal with no falsifying signal, abort threshold, or verified rollback).
- **Next action:** stop when no rollback exists or abort criteria are unmeasurable; get a second reviewer when only one has seen the reasoning.

# Double-Checking Before Acting

## Overview

A self-check turns a high-stakes action into a careful one. Before you claim success, name the target, the result you expect, when to stop, the action itself, and the check you will run afterward.

## Decision contract

- **Claim checked:** the target, expected result, and stop condition were named before the action, and the real result was compared against the expected one before claiming success.
- **Artifact observed:** the proposed action, target, and authority -> a `self-check.md` note of action, target, expected/real result, stop condition, evidence, and any mismatch.
- **Decision affected:** block -- whether to proceed with or abort the critical action: a big edit, command, public claim, trust change, or release.
- **Failure class:** wrong-target-or-unverified-action (acting on an assumed target, or claiming success without comparing the result).
- **Next action:** pause and escalate when authority, target, or evidence is unclear; a mismatch halts the action rather than triggering a retry.

# Handing Off Work

## Overview

A handoff transfers responsibility, not just context. The next person or agent has to know what changed, what is left, what they are allowed to do, and when to stop.

## Decision contract

- **Claim checked:** the receiving owner can resume without the chat history -- the last finished action, changed conditions, remaining scope, authority limits, open evidence, and stop conditions are all stated -- and the owner has restated scope, authority, proof owed, and when to stop before acting.
- **Artifact observed:** the change-record path, current phase, mode, the done/changed/assumed/open state, and the authority limits -> a `turnover.md` with the resume point, what changed, what remains, the next decision gate, and the incoming owner's confirmation.
- **Decision affected:** block -- whether the receiving owner may resume, or must hold and re-question first.
- **Failure class:** open-loop-handoff (state only implied, or the owner acts before confirming scope and stop conditions).
- **Next action:** make the incoming owner restate scope, authority, and stop conditions first; escalate when credentials, production data, or release authority are involved.

# Learning From Experience

## Overview

Lessons from real operation (OPEX) only help if they change future work. So treat agent mistakes, near misses, review surprises, sloppy analysis, and support tickets as feedback. Each one shows you where a control was weak. A control is anything that steers behavior, like a test, a checker, a rule, or a permission limit. Use the lesson to make that control stronger.

No-blame applies to honest error and at-risk slips: the point is to fix the control, not the person or the model. It does not extend to a willful violation — knowingly disabling a control, fabricating a passing result, or routing around a required gate. Surface that and correct it as a finding; never file it as "just a mistake," and never normalize it (Charter Art. 3, 19). A bypassable gate is also its own weak control, so the lesson fixes both the violation and the gate that allowed it.

## Decision contract

- **Claim checked:** the event is stated as actual-versus-standard with a root cause and weak control named, and closes with an owned, verified control fix or a deliberate waiver saying why no fix was needed.
- **Artifact observed:** the event, near miss, or operating signal and the control it touched -> an OPEX record with the finding, action, owner, and evidence or close-out reason.
- **Decision affected:** block -- whether a durable control (test, template, prompt, monitor, checker, or baseline) is updated, or the lesson is explicitly waived with a reason.
- **Failure class:** unlearned-lesson (a fix with no control change, or a record closed with regret instead of a fix).

# Organizing Project Folders

## Overview

Folders are a real engineering decision, not an afterthought. Each folder is a choice about what to group. A good folder maps to one piece of the work breakdown or one disposition rule (what eventually happens to its contents: kept, temporary, archived, or generated). It holds things that change together. In other words, it has high cohesion (its contents share one reason to change) and low coupling (it does not depend tightly on other folders). Its name is safe on any platform, sorts cleanly, and is easy for tools to read.

This skill puts a folder-decision checklist in front of the agent, so folders get reasoned about instead of created by default. When the structure is a step-by-step agent workflow, it also applies the Model Workspace Protocol: numbered stage folders, a context file per stage, layered context, and review gates between stages. That workflow shape is a named path of its own — see `docs/02-operating-system/agentic-workflow-architecture.md` for when folders are enough (and when a durable runtime is not), and `templates/standard/stage-contract.md` for the full per-stage contract a release-bearing or delegated stage uses.

## Decision contract

- **Claim checked:** every folder maps to one work-breakdown piece or disposition rule with one home, its contents share one reason to change, and its name passes the naming/depth/path checks.
- **Artifact observed:** the work breakdown, its dictionary, and the current tree -> a folder map (outline number to path with disposition), per-folder README stubs, and a naming/depth/single-source check.
- **Decision affected:** warn -- accept vs rework the folder layout, or where a given file belongs.
- **Failure class:** junk-drawer-layout (a folder mapping to no piece or rule, or one idea with two homes).

# Proving Claims

## Overview

Evidence should answer named claims. It should not just create a vague sense that the change is fine. This skill turns each claim into a proof you can trace. It keeps six things apart: a fact, an assumption, an unknown, a source claim (something a source says), local proof (something you checked yourself), and decision authority (who gets to decide).

Boundary: this skill builds the claim-to-evidence trace that feeds other decisions. It does not decide whether to ship (`checking-release-readiness`), determine whether public legal/safety wording overpromises (`checking-legal-and-safety-wording`), validate source lineage (`checking-source-claims`), or create packet files (`creating-change-records`).

## Decision contract

- **Claim checked:** every material claim is tied to evidence, a stated gap, or a deliberate deferral, no claim reaches past its evidence, and the load-bearing claim's evidence is reproducible by an independent party or independently authored — not the actor's own narration.
- **Artifact observed:** `basis.md`, test, and review evidence -> claim-to-evidence rows with a status (`pass`/`fail`/`gap`/`deferred`/`not applicable`/`planned`) in `trace.md`/`verification.md`.
- **Decision affected:** warn -- the evidence posture that later `ship.md` release-readiness weighs.
- **Failure class:** overreaching-claim (a claim stated past its evidence, or a `fail`/unowned `gap` carried as shippable).

# Questioning Attitude

## Overview

This is the front door. Before an agent builds, merges, or releases, find the real question the work has to answer. Trust facts over confidence. Say out loud what you are not sure about. And stop the moment a doubt would change what you decide.

## Decision contract

- **Claim checked:** the change is restated as one decision question evidence could settle, each assumption is checked, marked a gap, or assigned, and the one fact that would change the decision is named.
- **Artifact observed:** the request/diff/plan/dependency -> a questioning-attitude write-up (or `questioning-attitude.md`) of assumptions, unknowns, shaky sources, and stop conditions.
- **Decision affected:** warn -- the Quick/Standard mode choice routed into `rating-change-risk`, and whether to proceed, escalate, or stop.
- **Failure class:** unexamined-assumption (an unchecked assumption driving the build, or a claim with no evidence).
- **Next action:** raise the mode or escalate/stop when a load-bearing assumption is a gap; otherwise proceed with the gaps named.

# Rating Change Risk

## Overview

Sort the change before you build it. That way the care you take matches the stakes and the evidence the change needs. The result is a mode choice, tied to the decision question, what the change must prove, and the triggers to escalate. Choosing the mode is how Nuclear-grade *tailors* rigor to stakes — the same idea project-management practice calls tailoring; see `docs/02-operating-system/risk-tiers-and-modes.md`. Mode is about how much rigor; it is orthogonal to the work type (greenfield, brownfield, defect-fix, or refactor-migration), which is classified upstream in `questioning-attitude` and shapes which questions you ask. See `docs/02-operating-system/work-type-lens.md`. The archetype classified there sets a **floor** under the mode you pick (see `docs/02-operating-system/archetype-lens.md`); if the archetype shifts mid-change -- the prototype someone decides to ship -- re-grade, because the stakes moved even though the diff did not.

## Decision contract

- **Claim checked:** the chosen mode matches the stakes -- Quick only for local, easy-to-undo, easy-to-prove work that adds no new trust boundary, and Standard or stronger once consequence, exposure, reversibility, detectability, unknowns, or agent power cross the line -- and the proof that mode owes is named.
- **Artifact observed:** the request/diff, the files/dependencies/credentials/APIs/users touched, `activation-thresholds.md`, and any prior `risk.md` -> the mode, decision question, evidence bar, required files, proof command or gap, and escalation triggers in `risk.md`.
- **Decision affected:** block -- the mode (Quick / Standard / stronger) and the evidence obligation that mode sets.
- **Failure class:** underrated-mode (a mode picked from effort, not stakes, weaker than the obvious consequence).
- **Next action:** raise the mode to fit the stakes; escalate when money, sensitive data, irreversible actions, autonomous tools, or release readiness are involved.

# Recording a Known-Good Version

## Overview

A baseline is simply the version everyone agreed is correct and wants to protect. This skill writes down that version, the evidence that backs it, and the things that would make it out of date.

## Decision contract

- **Claim checked:** the accepted version can be rebuilt exactly from its named commit/PR/release, everything under control is either included or deliberately left out, the accepted residual risks have owners, and the triggers that force a new known-good version are recorded.
- **Artifact observed:** `controlled-items.md`, `change-impact.md`, `verification.md`, the `ship.md` decision, and the identifying commit/PR/release -> a `baseline.md` with included/excluded scope, accepted gaps, and re-record triggers.
- **Decision affected:** warn -- the accepted baseline the ship decision produced, and the triggers that invalidate it.
- **Failure class:** unrebuildable-baseline (a version recorded as accepted with missing evidence or silently dropped scope).
- **Next action:** record the missing link or excluded scope as a named gap; escalate when the version affects customers, regulated work, or outside trust.

# Recording What an Agent Did

## Overview

A "does it work" check proves what an agent produced, not how it got there. Sometimes how it got there matters: for debugging, for auditing, for reviewing cost, or for defending a release decision. This skill says what to record about the run, how much detail to capture, and how to link it into the packet's `trace.md` and `verification.md` as evidence someone else could reproduce.

## Decision contract

- **Claim checked:** every step that mattered -- tool call, edit, command, API call, approval -- has a recorded result and status, and each stayed inside the power `basis.md` granted.
- **Artifact observed:** the run log/transcript/trace export against `basis.md` and `plan.md` -> step-level trace rows, decision-point and approval records, and a token/delay summary in `trace.md`/`verification.md`, linked to `ship.md`.
- **Decision affected:** warn -- the step-level execution evidence the `ship.md` decision relies on.
- **Failure class:** unevidenced-run (a stayed-in-scope claim with no step-level evidence, or unexplained cost).
- **Next action:** record the gap for `ship.md`; a power breach or unexpected side effect escalates to pause/incident.

# Reporting Shared Defects

## Overview

A defect you find in something other people use is two problems, not one. The first is the bug itself, which you fix. The second is that every other consumer of that shared or supplied artifact still carries it and does not know. Fixing your own copy and moving on leaves them exposed. This skill makes the outward notice a first-class obligation alongside the local fix, so a defect in a shared prompt, skill, dependency, model, eval, or template reaches the teams, agents, and releases that depend on it.

## Decision contract

- **Claim checked:** a defect found in a shared or supplied artifact has been evaluated for downstream impact and either notified to the affected consumers with an owner and a tracking link, or recorded as not-reportable with a reason -- never fixed locally and forgotten.
- **Artifact observed:** the defect, the shared or supplied artifact it lives in, and who consumes it -> a shared-defect report (description, affected consumers, severity, notice sent, owner, link) tied to the OPEX record and the deficiency register.
- **Decision affected:** block -- whether downstream consumers are notified (the local fix is not complete until they are), or the defect is recorded as not-reportable with a reason.
- **Failure class:** silent-local-fix (a defect in a shared artifact patched in one place while other consumers keep carrying it, unnotified).
- **Next action:** evaluate downstream impact and notify the affected consumers or owners; escalate when the defect touches security, data integrity, credentials, privacy, or a public release.

# Responding to Incidents

## Overview

In a casualty you stabilize first and analyze second. An incident is run by one named commander, keeps known facts separate from guesses, prefers reversible moves while the picture is unclear, communicates on a fixed cadence, and does not close until corrective actions are tracked to done. The goal is to stop the harm and preserve the truth of what happened, not to find blame in the moment.

## Decision contract

- **Claim checked:** the incident has one named commander, a timeline that keeps confirmed facts separate from hypotheses, and corrective actions that each carry an owner and a definition of done -- none left as "we should."
- **Artifact observed:** the current symptom, what changed, who can authorize rollbacks/failovers/comms, and the reversible actions available -> an `incident.md` (timeline, facts-vs-hypotheses, decisions, comms), owned corrective actions with closure triggers, and a handoff to learning and deficiency records.
- **Decision affected:** block -- whether the incident is stabilized and its corrective actions are owned with closure triggers (it stays open until then).
- **Failure class:** premature-incident-close (closed with unowned actions, or a hypothesis recorded as fact).
- **Next action:** stop a proposed irreversible fix until the cause is confirmed or risk is accepted by a named owner; keep the incident open until actions are owned.

# Reviewing Code Quality

## Overview

Standards drift in code is the slow buildup of complexity. Files grow until no one can hold them in their head. Layers get added that do not pull their weight. Logic for one feature leaks into shared code. Clever, hard-to-follow code replaces plain, direct code. Each step looks fine on its own. Added up, they make a system no one can maintain. This review holds the line and keeps standards rising. Its strongest move is deletion: prefer removing structure over moving it around. It ends in one honest verdict, not a softened summary. A review that always says "looks good" is not a control. The cost is not only human: a controlled minimal-pair study found a coding agent on cleaner code used roughly 7-8% fewer tokens and revisited already-edited files about a third less often, at an unchanged pass rate -- so drift is also a standing tax on every future agent run. That study's authors are affiliated with a code-quality vendor whose product the finding favors, it covered one agent over six repository pairs, and it improved cost rather than correctness; treat it as an argument about price, not about capability (fuller boundary in `docs/02-operating-system/token-burn-control.md`).

## Decision contract

- **Claim checked:** the diff was read against its goal, deletion was considered before rearranging for each complexity finding, and the verdict matches the findings -- an INCONCLUSIVE verdict naming the missing evidence.
- **Artifact observed:** the diff or module, its mission anchor or goal, and the shared-versus-feature layering map -> a ranked findings list (each with location, standard at risk, concrete fix) and one verdict with a reason.
- **Decision affected:** block -- one verdict on the diff or module: VERIFIED, NOT VERIFIED, or INCONCLUSIVE.
- **Failure class:** standards-drift (oversized files, thin pass-through layers, feature logic in shared code, or clever indirection accepted as fine).
- **Next action:** return NOT VERIFIED for the owner to decide, or INCONCLUSIVE naming the missing context; standards drift that recurs escalates to a control.

# Running a Review Panel

## Overview

The repo already says high-consequence verdicts should use a panel, and that "a panel that shares one biased brief is not three independent views, it is one view voiced three times" (`docs/02-operating-system/evaluation-integrity.md` §4). It has not said how to build one. This is that procedure. Its central move is making each seat declare the axis it varies -- model family, mechanism, brief, or human judgment -- because a panel's worth is not its headcount but the number of ways it can fail differently. It also separates the panel's *result* from its *health*: a panel degraded to two correlated seats still returns a confident unanimous verdict. And nothing it says is actionable until checked against live source here -- a blocking finding is a reason to look, not an authorization to fix.

## Decision contract

- **Claim checked:** each seat names the diversity axis it varies, distinct-axis count is recorded separately from seat count, material dissent is preserved rather than averaged, and every actionable finding carries a host-verified state.
- **Artifact observed:** the frozen packet, the seat roster with declared axes, each seat's independent first-pass response, any challenge-round responses, and the degradation record -> `panel.md` plus Evidence IDs in `verification.md`.
- **Decision affected:** block -- does the panel's verified finding set support the underlying verdict, or does dissent or degradation escalate the call to a human?
- **Failure class:** false-independence (correlated seats counted as separate views, consensus treated as proof, dissent averaged away, a degraded panel reported as full, or an unverified finding acted on).
- **Next action:** record result and health together, verify each actionable finding against live source, and escalate a split or degraded panel rather than resolving it by vote.

# Staying on Mission

## Overview

Mission drift is when an agent keeps shipping work that no longer serves the original goal. It comes in two forms. The first is intent drift: scope creeps, the goal quietly gets swapped for a smaller one, or the agent wins the task but loses the mission. The second is standards drift: the work gets a little less careful each time you accept one more small exception. Letting a bad habit become normal this way is called the normalization of deviance.

This skill keeps a written mission anchor in front of the work. When an action stops serving that anchor, you make one of three choices: re-anchor, escalate, or stop. The anchor has three parts: the goal, the success criteria (how you know you are done), and the clear non-goals (what you are deliberately not doing). One named person owns the anchor. That person is responsible for whether this change still serves its mission. Every small action still has to trace back to that larger mission.

The anchor is also the clarity that lets authority move to the edge: it is the commander's intent that keeps a decentralized decision aligned with the goal. Push decisions to where the information is, but only against a clear, shared anchor — otherwise local wins quietly drift from the mission.

## Decision contract

- **Claim checked:** the current action was tested against the written anchor's goal, success criteria, and non-goals, the loop and attempt count were actually run, and any crossed non-goal or loosened standard has a justification row, not a quiet edit.
- **Artifact observed:** the written anchor (`.nuclear/mission.md`, `## Mission anchor` in `risk.md`, or `.nuclear/charter.md`) and the current action/diff -> a recorded continue/re-anchor/escalate/stop decision, updated anchor, and any justification row.

# Stress-Testing Agent Changes

## Overview

When an agent can use tools, read data, or affect releases, it gives attackers something to aim at. Normal "does it work" testing does not test for that. This skill is about attacking your own work on purpose to find weak spots (red teaming). You do it in an orderly way: list the kinds of attacks that matter here, say what safe behavior should look like, try the attacks (or simulate them), write down what happened, and tie the findings into the packet's evidence record.

## Decision contract

- **Claim checked:** each attack type chosen for this setup has a recorded `contained`/`uncertain`/`exposed` result with expected behavior written before the result, no finding quietly dropped, and `python tools/ng.py validate .nuclear/changes/<slug>` passes.
- **Artifact observed:** `basis.md`, `risk.md`, and past OPEX records naming the agent role, tools, and data reach -> a red-team record in `verification.md` (or `red-team.md`) with each type's result, leftover risk, and backup controls.
- **Decision affected:** block -- per adversarial class, contained / uncertain / exposed; uncertain or exposed findings feed `ship.md`.
- **Failure class:** unhardened-agent-power (an unchecked attack type, or an exposed finding shipped with no named leftover risk).
- **Next action:** name leftover risk and backup controls in `ship.md`; an `exposed` finding touching credentials, production data, or users escalates.

# Tracking Deficiencies

## Overview

A deficiency you have decided to live with quietly becomes the new standard. This skill keeps a standing register of known problems so each one is aged, owned, and either fixed or formally accepted as risk with a named owner and a revisit date. The aim is to stop the slow normalization of deviation — the small erosions that, uncorrected, become the culture.

## Decision contract

- **Claim checked:** every tracked deficiency has a visible first-seen age, a named owner, and a disposition -- a fix-by date or a formal risk-acceptance with a named owner and a concrete revisit trigger -- never "known, untracked."
- **Artifact observed:** the deficiency, where it shows up, its consequence and frequency, and any related incident/OPEX/controlled item -> a deficiency entry or `deficiency.md` row (description, age, owner, disposition, review trigger) linked to those records.
- **Decision affected:** block -- per deficiency, fix by a date or formally risk-accept it with a named owner and a revisit date.
- **Failure class:** normalized-deviation (a known problem living in chat/memory, or an accepted risk with no owner, date, or trigger).
- **Next action:** assign an owner and a fix-or-accept disposition; escalate when it touches safety, security, data integrity, or drives repeat incidents.

# Using Nuclear-grade

## Overview

This is the always-first router for Nuclear-grade work. Before you act, classify the change by consequence and route to the matching rigor — move fast while ideas are throwaway, slow down the moment the work becomes a promise. Start by asking the real question the change must answer, then state the mode it earns and the one fact that sets it. Build the smallest change record that does the job, prove the claims that matter, and say the release decision out loud.

The repo charter (`.nuclear/charter.md`) holds the lasting rules every change follows. Each change also gets a goal anchor — what that one change is for — so the work does not drift off course.

## Decision contract

- **Claim checked:** this change is named the cheapest-fitting mode -- the administrative floor, Quick, or Standard-plus -- with the one fact that sets it stated before the first tool call, and any Standard-plus trap (auth, user-visible, data, dependency, model/prompt/agent power, CI, release) forces the stronger mode.
- **Artifact observed:** the request, diff, and any record under `.nuclear/changes/` -> the declared mode, its one-fact reason, and the change-record path that routes the work into its skill cluster.
- **Decision affected:** block -- the mode declared before the first tool call (the administrative floor, Quick, or Standard-plus) and the skill cluster it routes into.
- **Failure class:** unclassified-or-downgraded-start (work begun before a mode, or a Standard-plus trap waved off as Quick).

# Verifying Final Artifacts

## Overview

Reviewing the code, config, or markup that *produces* a figure, chart, PDF, or interface -- and calling it done without opening the actual output -- is validating the recipe, not the meal. The generator is not the artifact. A plotting script can be correct line by line and still emit a figure with overlapping labels, a substituted font, a clipped axis, or a legend off the page. A LaTeX source can compile "cleanly" into a PDF whose table breaks across a page boundary. A UI component can look right in source and render broken. A deploy config can be valid and the live endpoint still return the wrong body.

The delivered artifact is the only thing the consumer ever sees, and the only place these defects appear. None of them is reliably predictable from a source read. This skill holds that line: it regenerates the artifact fresh, observes the real output the way a consumer would, compares it to the spec, and loops -- fix the source, regenerate, look again -- until the observed artifact is right or a stop condition is hit. It ends in one honest verdict, not a verdict inferred from "the diff looks correct."

## Decision contract

- **Claim checked:** the final delivered artifact, freshly regenerated this pass and directly observed, meets its spec or acceptance criteria -- the source that generates it was not accepted as a stand-in for the output.
- **Artifact observed:** the regenerated output itself (the image opened, every PDF page rasterized and read, the UI screenshotted, the endpoint response fetched) compared against the spec or reference -> a findings list, each defect tied to a location in the *output* and the source line responsible, plus one verdict.
- **Decision affected:** block -- whether the artifact ships as-is, or the source must change and the artifact be regenerated and re-observed before it can ship.
- **Failure class:** source-proxy error (approving the generator in place of the thing it generates) or stale-artifact error (reviewing a cached or old export instead of a freshly regenerated one).

# Vetting Outside Code and Models

## Overview

Trusting outside code is really a decision about how you will use it. A dependency, model, API, SaaS tool (software you rent online), or vendor claim should be accepted only for the job its evidence and controls actually support. Trust it for that job. Do not trust it past that.

## Decision contract

- **Claim checked:** the dependency, model, API, or SaaS is accepted only for a use no broader than repo-side evidence supports, its critical characteristics independently verified by a named acceptance method, vendor claims kept apart from proof, each gap given a re-check trigger or routed to a release decision; a critical characteristic that cannot be independently verified blocks acceptance.
- **Artifact observed:** the named dependency/version/provider, vendor claims, and own-repo evidence -> a supplier-trust section or `supplier-trust.md` with the use decision, gaps, backup controls, and release impact.
- **Decision affected:** block -- whether to trust and use the dependency, model, API, or SaaS; unresolved gaps feed `ship.md` defer/block/ship-with-risk.
- **Failure class:** boundary-overreach (trust stated past repo-side evidence, or vendor marketing treated as proof).
- **Next action:** route the unresolved gap to `ship.md`; credentials, production data, or security/privacy claims escalate to a qualified review.