delete-module-safely
Skill8 starsChanged 10 days agoApache-2.0View on GitHub
Delete a dead/fabricated module (or module family) — or a WRITE to a shared slot — without stranding importers, readers, tests, CI jobs, or docs. Use for any fix-or-delete execution, Tier-3-style dead-code removal, or retiring a superseded subsystem. Encodes the Finish-the-Unfinished sprint's deletion lessons (Families 1-3, 2026-07-18/19).
In this repository39 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- .cursor/rules/architecture-patterns.mdcCursor rule
- .cursor/rules/completion-discipline.mdCursor rule
- .cursor/rules/github-tracking.mdcCursor rule
- .cursor/rules/programmer-briefing.mdcCursor rule
- .cursor/rules/verification-first.mdcCursor rule
- ab-a-isolationSkill
- assign-sprint-safelySkill
- audit-cascadeSkill
- brief-coding-agentSkill
- check-mailboxSkill
- cleanup-dev-activeSkill
- close-issue-properlySkill
- cohort-attention-rollupSkill
- compost-reviewSkill
- continue-narrativeSkill
- create-omnibusSkill
- create-session-logSkill
- cut-releaseSkill
- deliver-mailSkill
- discovered-work-captureSkill
- doc-sync-sweepSkill
- draft-blog-postSkill
- draft-weekly-shipSkill
- duty-cycle-tickSkill
- narrative-verificationSkill
- piper-draft-issueSkill
- piper-draft-specSkill
- piper-sprint-planSkill
- piper-stakeholder-updateSkill
- piper-synthesize-feedbackSkill
- propose-featureSkill
- publish-to-blogSkill
- query-github-boardSkill
- template-auditSkill
- trust-checkSkill
- update-calendarSkill
- update-current-stateSkill
- update-piperSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 105
Run the surgered test files.
- Distinctive: line 109
If CI enforces anything about the deleted paths (coverage targets, perf baselines, import-based jobs), fix the workflow in the SAME push or …
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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
delete-module-safely
Deletion is fabrication-removal, not tidying: a dead module that LOOKS live (imported, tested, CI-enforced) manufactures false confidence. This skill makes the removal itself trustworthy. Born from three executed deletion families (#1436 Tier-3, 2026-07-18/19) whose lessons repeated verbatim across days — and from the near-misses each one caught.
Rule 0 — ruling before cutting
A module not already ruled deletable by Arch (or PM) gets a proposal memo with FRESH caller evidence first. Protected representations (spatial intelligence) are NEVER deleted without the PM-directed review completing, regardless of coldness. When a sweep surprises you mid-execution (an unruled orphan appears), flag it in the execution memo — precedent: riders whose sole purpose is the deleted thing may ride, but say so explicitly.
The sweep (before EVERY cut) — enumerate the whole space
A sweep blind to part of its space gives false confidence (the blind-sweep
class, 6 instances named by Arch). For module pkg.mod:
- Both import styles — absolute AND relative:
from pkg.mod import·from pkg import mod·import pkg.mod·from .mod import·from ..sub.mod import(Family-1 near-miss: absolute-only grep missed a live RELATIVE importer; caught only by test collection.) - Init re-exports —
pkg/__init__.pyre-exporting the module's classes creates a second import path (from pkg import ClassName); sweep the CLASS names from the package, not just the module name. - Precise patterns — an over-broad regex INVENTS importers (the inverse
blind spot: a
from \.$modpattern matched other packages' relatives and nearly kept a dead module alive). Anchor patterns to the real package path. - Function-local imports — module-level grep misses
importstatements inside functions (two dead scripts survived a Family-2 sweep this way). Sweep the module NAME repo-wide, then classify each hit. - Non-code referents — CI workflows (a deleted directory was still a
--covtarget and an inline-python import in test.yml), scripts/, docs that describe the module as live, config files listing its paths. - ALL python roots, not just services/+web/+tests/ — sweep
cli/,coordination/,rag/,shared/,skunkworks/,suggestions/,tools/,alembic/,scripts/too.cli/is pytest-invisible (testpaths=tests) and was outside the 2026-08 census denominator; it held a live importer of a Batch-3 target AND a broken import of a Batch-1 deletion that nothing surfaced for a day (#1700, 2026-08-30). A root no collector touches is exactly where a stranded importer hides silently. And don't| head-truncate sweep output — truncation hid two dedicated test files in the same batch; usegrep -rlfile-level output instead.
Deleting a WRITE, not a module — enumerate the slot's READERS first
(Added v1.1, 2026-09-18, Arch — from #1810/#1814, and it is MY ordering error being codified, not a lane's.)
The sweep above is module-shaped: it enumerates importers of a thing that is going away. A write-deletion is the sibling case and the sweep above cannot see it — the module stays, the slot stays, only the producer goes. Nobody greps for "who reads this slot," so nothing fails.
The rule: before deleting a write, enumerate every reader of that slot and NAME each one's post-deletion source. Not "the readers still resolve whatever is there" — true, and worthless the moment the slot empties. An actual list: reader → where it gets the value once this write is gone.
The worked case: #1810 deleted a global LLM-key write (a real cross-user credential leak — the right call). The readers were left pointing at the now-permanently-empty slot, so a BYOC user's key was stored and never read: every substantive query hit a false "not configured" wall (#1814). A billing leak was converted into a functionality wall, and it landed the day an external tester's invite was ready. The ruling that ordered the deletion had the reader/writer picture in front of it and gated only the write.
Two tells that you are in this case and not the module case:
- the thing you are deleting is a statement, not a file;
- the grep that would reassure you ("who imports this?") returns the same answer before and after your change.
And the reader enumeration is evidence, not narration — it goes in the ruling or the issue, with each source named, so a reviewer can check it. If a reader has no post-deletion source, that is a precondition to fix first, not a follow-on to file.
The cut
git rmexplicit paths only. Family tests (dedicated test files) ride the same commit; live-subject test files get SURGERY (excise the coupled fixtures/tests, keep the file) — read the file's structure first, never wholesale-delete a mixed file.- Package
__init__edits preserve surviving exports. - Stale docstrings/comments in SURVIVING files that name the deleted module get corrected in the same commit (a doc claiming a deleted reader is live is a small fabrication).
Verify AFTER each excision (not just at the end)
- py_compile every edited file (a dangling kwarg from an incomplete old-string is a real occurrence).
- Full test COLLECTION (
--collect-only) — collection catches live importers the sweep missed. - Run the surgered test files.
- Full ratchet suite after every delete batch — deleted modules carry debt instances (TODO markers, silent-death sites, mypy errors); shrink-locks fire and ceilings lower in the SAME commit. Selective re-runs missed drops twice.
- If CI enforces anything about the deleted paths (coverage targets, perf baselines, import-based jobs), fix the workflow in the SAME push or CI goes red at the tip.
- cli/ has its own import-smoke gate since #1700 (2026-09-24):
tests/unit/cli/test_cli_commands_import_1700.pyparametrizes over everycli/commands/*.pymodule discovered from the filesystem andimportlib.import_modules each one, markedsmoke. It runs under normal pytest collection (testpaths=testscoverstests/unit/cli/) — this is what makes a deletion that breaks a cli/ importer loud now, where before #1700 nothing surfaced it for a month. A module deletion that orphans a cli/commands/*.py import will fail this test; fix-to-live-path or dispose the command in the SAME push, per Rule 0.
Read every verdict whole (v1.3, 2026-11-06, CIO's skills-review fold)
Three habits the 09-24 → 10-10 logs (Lead, Arch, prog) kept relearning. A deletion moves counts in places nobody looked, so these are part of the cut, not extras:
- A sweep or gate's verdict is its exit code plus its whole output. Never
| taila pytest or gate run and read the last line:tailexits 0 whatever pytest did, and the failed names sit above the summary (Lead pushed red pins twice on 10-30 that way; a mypy section above the tail was missed on 09-25). Capture to a file, grep^FAILED, and check${pipestatus[1]}. - A router or catalog change from a deletion is scored on both tables: the ×6 sentinel table (the rows the change is for, plus the named neighbours) AND the full-corpus ×1 table, against a bar set before the run (rule 7). A deletion that wins its target rows and scatters unrelated ones is NO-GO; the full table is where the scatter shows.
- A literal or pattern-list deletion push runs enforcement whole:
tests/test_architecture_enforcement.pyandtests/test_completion_ratchets.pyin full, not the one ratchet you expect to move. Deleted literals shift shrink-locks and ceilings in sibling ratchets, and those must move in the same commit.
The record
- decisions.log entry: WHAT IT EXISTED FOR (one line of history), the ruling reference, the evidence (importer sweep result, collection count), and any supersessions (an issue obviated by deletion closes as superseded with the paper trail — description-first per close-issue-properly).
- Preserve genuinely-novel design thinking as a design-record doc BEFORE deleting (PM-033d precedent) — git history holds code; it doesn't surface ideas.
Anti-patterns
| Don't | Because |
| Absolute-only import grep | Relative importers stay live and break at runtime/collection |
| Trust "N importers" from a loose regex | Over-broad patterns invent importers; under-broad hide them |
| Delete a mixed test file for one dead class | You just deleted live coverage |
| Skip the ratchet suite "because it's a delete" | Deletes SHRINK counts; unlocked ceilings fail the next run |
| Leave CI enforcing the deleted thing | A gate about deleted code is a false-gate — worse than none |
| Batch the decisions.log entry "for later" | The record rides the commit or it doesn't exist |
Changelog
- v1.3 (2026-11-06, Lead, CIO's skills-review fold, xian's 10:05 acceptance):
added "Read every verdict whole": whole-output and exit-code reading, both
tables for a router change, enforcement whole before a literal push. The first
was half here already (item 6's "don't
| head-truncate"); now it covers gates. - v1.2 (2026-09-24, Coding Agent for Lead, #1700): Documented the cli/
import-smoke gate (
tests/unit/cli/test_cli_commands_import_1700.py) that now makes item 6's cli/ sweep-root rule mechanically enforced, not just prose. Source: cli/'s ruled standing as a live operator surface (decisions.log 2026-09-24) plus a fresh sweep finding TWO more stale cli/ imports beyond the #1700-named one —cli/commands/keys.py'sKeyRotationService(deleted 2026-07-18, #1436 Tier-3) andcli/commands/notion.py's second dead import,notion_queries(deleted the same day) — both silently broken since July, both invisible until this gate existed to catch them. - v1.1 (2026-09-18, Arch): Added the write-deletion case (enumerate the slot's READERS with each one's post-deletion source named). The module-shaped sweep is structurally blind to it. Source: #1810 → #1814, an ordering error in my own ruling — a credential leak correctly closed, converted into a functionality wall because only the write was gated.
- v1.0 (2026-07-19, Lead Dev): Created from #1436 Tier-3 Families 1–3 execution lessons, per the 7/18 memory-eval gap ("worth codifying if Tier-3-scale deletion recurs" — it recurred the next morning).
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.

