agentleFS
AltinityAltinity/clickhouse-sink-connector/.claude/skills/destructive-operation-safety/SKILL.md

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

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
  1. Very specific:

    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 …

    line 69

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

  1. 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}")
  2. A Destructive-Op-Check: sites=<N>; result=pass commit trailer, where <N> is the number of destructive statements touched by the commit and result=pass asserts each one was reviewed against this checklist. The gate checks that the count in the trailer matches the number of DESTRUCTIVE:-marked sites actually found in the diff — a mismatch fails CI.
  3. 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=pass trailer 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.