destructive-operation-safety
Skill345 starsChanged 38 days agoApache-2.0View on GitHub
Use whenever a change adds or modifies a destructive statement or operation — DROP, TRUNCATE, DELETE, ALTER ... DROP, DETACH PARTITION, rm -rf, or an apply-mode run of a resync/repair tool. Defines the DESTRUCTIVE comment and Destructive-Op-Check commit-trailer convention that scripts/review_gates.py's destructive gate enforces in CI.
- Deletes or force-pushes
In this repository17 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- clickhouse-sink-reviewSkill
- code-quality-architectureSkill
- code-quality-bashSkill
- code-quality-goSkill
- code-quality-jvmSkill
- code-quality-pythonSkill
- code-quality-sqlSkill
- code-reuse-firstSkill
- code-reuse-reviewSkill
- design-note-debtSkill
- mandatory-code-change-validationSkill
- pr-self-reviewSkill
- repro-harness-negative-proofSkill
- sink-connector-mysql-source-of-truthSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 69
Before trusting a tool's --help text or a config flag's name to tell you whether an operation is safe, read the consumer code that actually …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Destructive Operation Safety
Overview
A past incident involving an under-reviewed destructive statement in infrastructure tooling caused unplanned data loss and led to this project's current convention: every destructive statement must be visibly marked, counted, and checked before merge — not caught only if a reviewer happens to notice it in a large diff.
scripts/review_gates.py's destructive gate enforces this
mechanically in CI. It cannot judge whether the blast-radius claim in the
DESTRUCTIVE: comment is actually true — that's still a human reviewer's
job.
The Three Requirements
A
DESTRUCTIVE:comment within 5 lines of each destructive statement, stating what it destroys and the expected blast radius:# DESTRUCTIVE: drops all rows in the target table for the given # partition before reloading from source; blast radius is one # partition, confirmed by the --partition argument above. cursor.execute(f"ALTER TABLE {table} DROP PARTITION {partition}")- A
Destructive-Op-Check: sites=<N>; result=passcommit trailer, where<N>is the number of destructive statements touched by the commit andresult=passasserts each one was reviewed against this checklist. The gate checks that the count in the trailer matches the number ofDESTRUCTIVE:-marked sites actually found in the diff — a mismatch fails CI. - A dry-run mode for any CLI tool whose normal operation is
destructive. This project's own resync/repair tooling (e.g.
sink-connector/python/ch_sink_tools/db_load/mysql_resync.py, which spec 13.08 documents as having distinct dry-run and apply modes) is the model to follow: the dry-run path must exercise the same logic as the apply path right up to the point of mutation, not be a separate, driftable code path that can silently stop matching reality. A new destructive tool added to this project should follow the same pattern.
Worked Example
-- DESTRUCTIVE: removes the old partition entirely before the
-- REPLACE PARTITION below swaps in the freshly-resynced data; if the
-- REPLACE fails partway, this partition is gone until the resync is
-- re-run. Blast radius is the single partition named above, confirmed
-- by the WHERE/partition-key filter on the preceding SELECT.
ALTER TABLE target_table DROP PARTITION '2026-09';
ALTER TABLE target_table REPLACE PARTITION '2026-09' FROM staging_table;Commit trailer: Destructive-Op-Check: sites=1; result=pass
The Cardinal Rule
Before trusting a tool's --help text or a config flag's name to tell you
whether an operation is safe, read the consumer code that actually executes
it. A flag named --safe-mode or a tool whose help text implies it only
reports differences can still issue a real DELETE/DROP under certain
argument combinations — the only way to know is to read what the code
actually does with the arguments it's given, not what its interface
suggests.
Review Checklist
- Every destructive statement in the diff has a
DESTRUCTIVE:comment within 5 lines - The comment states the actual blast radius, and that claim is verifiable from the surrounding code (a filter, a partition key, an explicit allowlist) — not just asserted
- The commit has a
Destructive-Op-Check: sites=<N>; result=passtrailer with the correct count - Any new destructive CLI tool has a working, logic-sharing dry-run mode
- The reviewer traced the actual consumer code for any flag or helper the PR relies on being "safe," rather than trusting its name or docs
Anti-Patterns
A destructive statement with no DESTRUCTIVE: comment · a comment that
states a blast radius that isn't actually enforced by the surrounding code
· a commit trailer whose count doesn't match the diff · a dry-run mode
implemented as a separate, unverified code path from the real one ·
trusting a tool's help text instead of reading what it executes.
Cross-References
pr-self-review, mandatory-code-change-validation, code-quality-sql,
code-quality-bash, sink-connector-mysql-source-of-truth.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

