Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions README.en.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@ Codebase entropy is rarely just an unused function. It can be duplicated state,

Static analysis can surface leads, but it cannot prove a deletion safe by itself. This Skill follows runtime consumers, dynamic registration, persisted formats, public interfaces, design history, and verification boundaries before classifying a candidate as remove, merge, retain, or unresolved.

It also recognizes implementation-shape guardrails: tests, static scans, inventories, and build/CI checks that constrain directory layout, literal source text, private defaults, exact component counts, or a historical implementation identity without protecting observable behavior. AI authorship is not removal evidence; business, API, security, persistence, concurrency, and real deployment guards remain ordinary live contracts.

> **Core principle:** deleted lines are an outcome. The durable gain is deleting a fact, state, contract, or concept that no longer needs maintenance.

## How it works
Expand Down Expand Up @@ -97,6 +99,12 @@ Use $simplify-codebase to remove one high-confidence source of accidental comple
Use $simplify-codebase to verify and integrate the simplification findings from this PR. Preserve evidence, not finding counts.
```

### Investigate implementation-shape guardrails

```text
Use $simplify-codebase to audit tests, build/CI, and static checks that only preserve an obsolete implementation shape. Do not modify files, and retain checks that still protect business, security, or deployment behavior.
```

## What it returns

A read-only survey returns coverage, ranked proof records, important counterexamples, unresolved questions, and the next fact needed for each uncertainty.
Expand Down
8 changes: 8 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@

静态检查可以提供线索,但不能单独证明一项删除是安全的。这个 Skill 会继续追踪运行时消费者、动态注册、持久化格式、公共接口、历史决策与验证边界,再决定应该删除、合并、保留,还是标记为暂时无法判断。

它也会识别“实现形态守卫”:只约束目录结构、源文本、私有默认值、固定组件数量或历史实现身份,却不再保护可观察行为的测试、静态扫描、清单和构建/CI 检查。AI 是否生成过这些代码不是删除证据;业务、API、安全、持久化、并发和真实部署守卫仍按普通契约保留。

> **核心原则:** 删除代码行只是结果。真正的收益是删除一个需要长期维护的事实、状态、契约或概念。

## 工作方式
Expand Down Expand Up @@ -95,6 +97,12 @@ git clone https://github.com/tt-a1i/simplify-codebase.git \
使用 $simplify-codebase 复核并整合这个 PR 中的简化建议。保留证据,不保留候选数量。
```

### 调查实现形态守卫

```text
使用 $simplify-codebase 审计测试、构建/CI 和静态检查里只保护旧实现形态的守卫。不要修改文件,并保留仍然保护业务、安全和部署行为的检查。
```

## 输出是什么样的

只读审计会交付覆盖范围、排序后的证明记录、重要反例、未决问题和下一条所需证据。
Expand Down
6 changes: 5 additions & 1 deletion SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: simplify-codebase
description: Simplification audit or authorized codebase simplification whose stated objective is to remove accidental complexity. Use for evidence-backed deletion or consolidation of dead code, duplicate state, redundant APIs or layers, ownerless abstractions, obsolete compatibility or design records, and over-engineering in any language; also use for 代码简化 or 熵回收. Do not use for general code review, onboarding, style-only refactoring, or performance tuning.
description: Simplification audit or authorized codebase simplification whose stated objective is to remove accidental complexity. Use for evidence-backed deletion or consolidation of dead code, duplicate state, redundant APIs or layers, ownerless abstractions, obsolete compatibility or design records, over-engineering, and tests or checks that preserve an obsolete implementation shape; also use for 代码简化、熵回收或 AI 防回退清理. Do not use for general code review, onboarding, style-only refactoring, or performance tuning.
---

# Simplify Codebase
Expand All @@ -14,6 +14,8 @@ First choose the authority mode:
- **Survey** for simplification audit, investigation, or candidate-finding requests. Remain read-only and return ranked evidence.
- **Change** for explicit simplify, remove, consolidate, refactor, or repository-documentation edit requests. Prove each cut, implement it within the authorized scope, and validate the surviving contract.

A request that only mentions defensive, anti-regression, or AI-generated guardrails without an explicit edit verb or other change authority remains Survey. AI provenance is not deletion evidence and does not lower the proof burden. When a request combines an implementation-shape guardrail with another simplification, keep separate proof records and cut boundaries even when they are validated in the same run.

Then choose the coverage scope:

- **Focused** when the user names a subsystem, symbol, state machine, dependency, or suspected duplication. Cover that boundary thoroughly before expanding outward.
Expand All @@ -36,6 +38,8 @@ The contract map is complete when all in-scope entrypoints and authority boundar

For every Broad engagement, and for Focused work involving dynamic architecture or dependency substitution, read [investigation.md](references/investigation.md). Build a coverage map before ranking findings; the first plausible deletion must not end the survey.

Also read [investigation.md](references/investigation.md) when tests, source scans, inventories, import bans, or build/CI checks may preserve an implementation shape rather than observable behavior. Apply its implementation-shape guardrail lens within the ordinary proof workflow.

For concurrency, cancellation, readiness, cleanup, defensive copies, validation, authorization, security isolation, accessibility, data-loss prevention, or cross-process data, also read [boundaries-and-lifecycle.md](references/boundaries-and-lifecycle.md).

Use repository-native search, compiler and linter output, dependency metadata, and history as discovery instruments. Treat their findings as leads until runtime consumers and contracts have been examined.
Expand Down
8 changes: 8 additions & 0 deletions docs/validation.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,14 @@ This document records the behavioral validation completed before the initial ope
- Expected behavior: prove the cut below file granularity.
- Result: the focused audit found 14 candidate-exclusive CSS classes, identified removable members inside mixed selectors, retained the shared stylesheet and surviving component, and found two stale documentation references.

### Implementation-shape guardrail

- Fixture: a small Node.js package with pricing and authorization behavior, an unexported dead helper, a deployment check, and a test plus script that asserted an exact source filename and function spelling.
- Ambiguous request: an independent Skill run was told only that defensive or AI-generated guardrails might exist. It selected Survey mode, made no edits, ranked the implementation-shape guard separately from the dead helper, and retained the quantity validation, authorization boundary, business tests, and deployment check.
- Focused change: an explicitly authorized run removed only `tests/layout.guard.test.js`, `scripts/check-layout.js`, and the `check:layout` package entry. The baseline passed 4 tests plus the layout and deployment checks; afterward all 3 surviving behavior tests and the deployment check passed. The operation receipt named every deleted artifact, its original check, the removal evidence, surviving behavior, reintroduction condition, verification, and undo path.
- Mixed objectives: an explicitly authorized run handled the shape guard and dead helper as separate proof records and cut boundaries. It removed 22 lines across 4 files with no replacement machinery, found no residue, passed syntax and diff checks, passed all 3 surviving behavior tests, and preserved the deployment check. The final receipt kept both cuts separate.
- Environment note: the Windows fixture runner used `npm.cmd` because the bare `npm` shim was unavailable; this did not change the fixture or expected behavior.

## Mechanical checks / 机械检查

- Skill structure and frontmatter validation;
Expand Down
4 changes: 4 additions & 0 deletions references/execution-and-recovery.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ Purpose: retire each proved obligation completely, validate the surviving system

Prefer one high-confidence ownership boundary over a mixed cleanup batch. The selected change should retire a complete obligation and have a decisive check. If investigation reveals a larger product choice or broader migration than the user authorized, present the ranked plan and obtain one scope confirmation before applying it.

When one request includes an implementation-shape guardrail and another simplification, preserve separate proof records and cut boundaries. Removing the guardrail must not become authority to remove the implementation it once described, or vice versa.

Pause application when dynamic or external consumers remain unknown, stored data lacks a migration story, baseline failures erase the intended signal, the cut crosses unrelated ownership boundaries, or rollback would be impractical. Convert the result into an evidence report with the exact missing decision or fact.

## Remove the obligation vertically
Expand Down Expand Up @@ -61,4 +63,6 @@ Undo: files or commit range to reverse and any data/config restoration required

The undo path must match the side effects. Source-only changes may be reversible from the diff; migrations, published packages, deployments, and durable data require explicit restoration steps and separate authorization.

For a removed implementation-shape guardrail, the existing `Artifacts` entry must identify each deleted file or materially deleted section and state its original check, decisive removal evidence, surviving behavior, reintroduction condition, and verification. Use the same receipt rather than creating a parallel delivery schema.

The batch is complete only when the structural cut criterion, every applicable verification ring, the complete diff audit, and the operation receipt are all satisfied or reported as unavailable with the resulting evidence limitation.
3 changes: 3 additions & 0 deletions references/investigation.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,9 +31,12 @@ Use these lenses to generate leads:
- **Local infrastructure**: custom parsing, retry, framing, matching, diffing, scheduling, or collection code duplicates a suitable platform feature or dependency.
- **Support drag**: tests, examples, snapshots, generated expectations, or documentation are the only reason an otherwise unused surface remains.
- **Feature fossil**: implementation was abandoned or removed while schema, configuration, tests, compatibility logic, or design records still preserve its outline.
- **Implementation-shape guardrail**: a test, source scan, inventory, import ban, or build/CI check enforces file layout, literal source text, private defaults, exact component counts, or a historical implementation identity without owning observable behavior.

Do not equate visual similarity with duplication. Independent implementations may test an interface, isolate failure domains, protect different owners, or support distinct compatibility contracts.

Do not use AI authorship or a label such as "defensive" as evidence that a guardrail is removable. Treat it as a candidate only when the consumer map shows that its remaining obligation is an obsolete implementation shape. Keep guards that protect business outcomes, public APIs, trust boundaries, security, persistence, concurrency, deployment acceptance, integration behavior, or an active engineering policy.

## Climb the evidence ladder

Classify each lead by the strongest evidence reached:
Expand Down