docs cleaner

Other Community

Skill notes

Core principle (governs both modes)

Critical evaluation before deletion. Never blindly delete. Analyze each section's unique value before proposing removal. The goal is reduction without information loss. This governs every deletion-shaped action in this skill, not just consolidation: archiving a document, dropping a derived value, and removing a cross-reference are all deletions and all owe the same analysis first. "It looked redundant" is not that analysis.

Which mode are you in?

The user said / the situation · Mode "I changed X" / a diff exists / a procedure was updated · 1 — Post-change governance "which docs are now wrong", "check for stale commands/paths" · 1 — Post-change governance "clean up the docs", "too many files on this", "merge these" · 2 — Consolidation A topic is spread over several files with no clear owner · 2 — Consolidation

The Drift Test (the core of both modes)

Before writing any value into a document — and when deciding whether an existing one earns its place — ask these three questions in order, and stop at the first hit: 1. Can this be computed from details already recorded here or in the authoritative source? → It is a derived value. Do not write it. Compute it when someone asks.

Position gives no exemption

A fact is a fact wherever it sits. All of these are body text for the purposes of the test above, and all of them are where stale values actually survive audits: frontmatter · YAML/JSON metadata · parenthetical asides · a description column in an index table · checkbox state · introductory framing before the real content · cross-document footnotes · an extra column added to a table · commit-message-shaped notes left in prose

What counts as a fact

Anything that changes over time and has an authoritative definition somewhere: numbers, status, ownership, relationships, classifications, rules, decision sources, dates, counts. Business rules count too — "all quotes route through the finance lead" is defined once and referenced, never restated in each downstream doc.

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Other
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@daymade · no license declared
Token usage
Moderate
Setup complexity
Guided setup
External API key
Not required
Operating systems
Unspecified (assume cross-platform)
Runtime requirements
Python
Detected file/system behavior
  • Read-only
  • Write / modify
  • Shell exec
  • Env read
Network behavior
External requests
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

01
Phase 1: Discovery

Identify all documentation files covering the topic, and state the boundary you searched within (a directory, a suite, one project) before you search — the same bounded-scope rule Mode 1 step 1 uses. Two agents given "the docs" and no boundary consolidate different file sets. A topic-keyword sweep inside that boundary is the usual method — note `-F`, since topic terms like `C++`, `.NET` or `v1.0.0` are literals

02
Phase 2: Value analysis

For each document, build a section-by-section table: Section · Lines · Value · Reason API Reference · 25 · Keep · Unique endpoint documentation Setup Steps · 40 · Condense · Verbose but essential Env Var Table · 30 · Delete · Duplicates the table in `README.md`, which is authoritative

03
Phase 3: Consolidation plan

Propose the target structure with real numbers, and present it for agreement — this is the plan Phase 4 asks you to get signed off before anything is deleted: The line counts and the reduction are measurements you can take now. "Value preserved" is not: at plan time it would be the deleting party asserting its own deletion was harmless, which is the self-certifying shape this skill exists to remove.

04
Phase 4: Execution

Deleting someone's documentation is irreversible from the reader's side even when git can undo it. Present the Phase 3 plan and get agreement before step 3. Phase 3 says "propose" for a reason; the Core Principle governs how carefully you analyze, not whether you are authorized. If you are running unattended and cannot ask, do steps 1–2, stop, and report what you would delete.

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.