Skip to content

docs: consolidate duplicated explanations and trim slop#3494

Merged
max-sixty merged 1 commit into
mainfrom
docs-slop-audit
Jul 16, 2026
Merged

docs: consolidate duplicated explanations and trim slop#3494
max-sixty merged 1 commit into
mainfrom
docs-slop-audit

Conversation

@max-sixty

Copy link
Copy Markdown
Owner

Sweep of the docs for repetition and filler, from an audit of the hand-authored pages, the command pages' source in src/cli/mod.rs, and the plugin skill. Net −574 lines; every cut either had a surviving canonical home or restated an adjacent sentence.

One home per mechanism (other mentions now link to it):

  • template-append — the LLM commits guide owns the rendering mechanism; the user- and project-config sections keep the key, an example, and what is unique to them (the project approval gate and the only-template-append-from-project scoping). Was explained in full in three places.
  • -vv diagnostic files — wt config state logs owns the four file descriptions; the FAQ summarizes in one sentence and links.
  • fsmonitor/trash cleanup — the FAQ's two overlapping wt remove bullets merge into one that distinguishes own-daemon teardown from the orphan sweep; troubleshooting.md's restatement compresses to a pointer, keeping its unique wedged-daemon-on-live-worktree guidance.
  • copy-ignored built-in excludes — the wt step copy-ignored page owns the directory list (previously enumerated 4×); the config sections state the rule and link.
  • hook-types table — wt hook owns it; the extending guide replaces its verbatim copy with a sentence.
  • LLM tool commands — unchanged, deliberately: the apparent hand-synced duplication between llm-commits.md and the config example is already machine-pinned by test_llm_docs_commands_match_config_example, so it cannot drift.

Cut-over debt: the deprecated wt config state ci-status section shrinks to a deprecation pointer — its status table, fetch order, and caching notes all duplicated the wt list CI-status section.

Structure: wt step copy-ignored's "Features" list dissolves into the sections that owned its facts (excludes → "What gets copied", reflink → "Performance"); the four trailing "Note: This command is experimental…" lines go (the [experimental] badge already appears twice per section); shell-integration.md described the directive-file mechanism twice and now describes it once.

SKILL.md drops from 339 to 181 lines: the permission-model section duplicated the config-types bullets, the hook-type mapping appeared twice, and the "Determining Which Config to Use" / "Validation Before Adding Commands" scaffolding enumerated judgments an agent makes on its own. The approvals-escalation and agent-handoff sections are untouched.

Deliberately not addressed: wt list's schema 1 JSON tables (still the default schema; the wholesale deletion lands when the default flips) and corpus-wide em-dash density (a house-style decision, not a per-page fix).

Generated mirrors (docs command pages, skill references, plugins mirror, dev/*.example.toml, help snapshots) regenerated via test_docs_are_in_sync and cargo insta.

This was written by Claude Code on behalf of max

Give each mechanism one home: template-append (llm-commits guide),
-vv diagnostic files (wt config state logs), fsmonitor/trash cleanup
(FAQ inventory), copy-ignored built-in excludes (wt step copy-ignored),
hook-types table (wt hook). Other mentions link instead of restating.

Shrink the deprecated ci-status section to a pointer, dissolve
copy-ignored's Features list into the sections owning its facts,
drop the four 'Note: experimental' lines redundant with the badge,
and cut SKILL.md's duplicated permission-model and hook-mapping
sections plus in-distribution scaffolding (339 to 181 lines).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@max-sixty max-sixty marked this pull request as ready for review July 16, 2026 20:38
@max-sixty max-sixty merged commit 568b6de into main Jul 16, 2026
40 checks passed
@max-sixty max-sixty deleted the docs-slop-audit branch July 16, 2026 20:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants