internal-docs-prune
Prune internal Claude-facing docs (CLAUDE.md, nested CLAUDE.md files, NOTES.md, .claude/rules/*.md) — spawns internal-docs-reviewer, auto-applies redundant/stale findings without content loss, and escalates judgment findings (interactive) or defers them (unattended)
- License 许可
- MIT
- 最近更新
- 2026-11-01
- Stars
- ★ 3
- Forks
- 0
01 前言 Front Matter
- name
- internal-docs-prune
- description
- Prune internal Claude-facing docs (CLAUDE.md, nested CLAUDE.md files, NOTES.md, .claude/rules/*.md) — spawns internal-docs-reviewer, auto-applies redundant/stale findings without content loss, and escalates judgment findings (interactive) or defers them (unattended)
- argument-hint
- [ "unattended" ]
03 SKILL.md 正文
Prune this repository's internal, Claude-facing documentation — the working
memory Claude itself maintains across sessions, as distinct from user-facing
docs/. This spawns the read-only internal-docs-reviewer agent, then
applies its findings by gating class.
The invocation is: $ARGUMENTS
Step 1 — Determine mode
Check $ARGUMENTS for an unattended token: unattended or --unattended
(case-insensitive, anywhere in the string). If present, run in unattended
mode. Otherwise run in interactive mode — the default.
The mode only changes how judgment findings are handled (Step 5). Both
modes apply redundant and stale findings identically (Step 4).
Step 2 — Identify scope
The in-scope surface is exactly what internal-docs-reviewer reviews: the
root CLAUDE.md, any nested CLAUDE.md files, NOTES.md, and
.claude/rules/*.md. Do not pre-filter this list yourself beyond finding the
candidate files (e.g. Glob **/CLAUDE.md) — the agent decides what is
actually reviewable within it.
This skill never edits anything outside this surface, with one narrow
exception: a move finding's named destination, which is always one of
features/COMPLETED.md, a named file under features/plans/, or a named
file under .claude/rules/ (the agent's own permitted destinations — see the
move action in its findings contract). Report-only or user-facing files
(docs/, README.md,CONTRIBUTING.md) are never touched, even if a finding
somehow named one - treat that as a defect in the agent's output (see Step 3)
rather than acting on it.
Step 3 — Spawn the reviewer and collect findings
Call @internal-docs-reviewer with the workspace root (or the specific in-scope files from Step 2) to review.
Parse its output into a list of findings, each carrying: Gating class
(redundant | stale | judgment), file path, Anchor (exact verbatim
text), Issue, Action (delete | move → destination | condense), and
Replacement/Destination text where the action requires one.
A finding missing a required field (see the agent's findings contract — every finding needs exactly one gating class and action, plus a destination/replacement wherever the action requires one) is a defect in the agent's output, not something to guess at: skip it, note it in the summary (Step 6) as "could not apply — incomplete finding", and do not act on it.
A finding whose gating class and action are an invalid combination is
likewise a defect — do not act on it. The agent's contract constrains the
pairing: a redundant finding's action must be delete (anything else would
duplicate content already at its canonical home), and a judgment finding's
action must be condense or move, never delete (the skill never silently
deletes content a human should decide about). If a redundant finding carries
move/condense, or a judgment finding carries delete, skip it and note
it in the summary as "could not apply — invalid class/action combination". This
means redundant/stale reaching Step 4 and judgment reaching Step 5 are
already known to carry a valid action.
If the agent reports no findings, skip to Step 6 and report a clean run.
Step 4 — Apply redundant and stale findings (both modes)
These are auto-applied in both interactive and unattended mode — no confirmation needed. Apply them file by file, largest/most-impactful first (the order the agent returns them in), and re-verify each anchor is still present, verbatim, in the file immediately before acting on it — an earlier finding applied to the same file can shift or remove text a later finding also depends on. If an anchor is no longer found, skip that finding and note it in the summary as "anchor not found — file changed since review, re-run to confirm."
For each finding, by Action:
-
delete— remove the anchor text entirely. Nothing replaces it. -
condense— replace the anchor text with the finding's exact Replacement text. -
move— this is the highest-consequence action (content leaving its only home) and the ordering below is not optional:- Read the destination file (create it only if the agent's Destination names a file that legitimately does not exist yet — this should be rare, since the three permitted destinations are established files).
- Write the Replacement/Destination text into the destination, in a
position consistent with that destination's own style (e.g. alongside
other entries in
features/COMPLETED.md, appended to the relevant section of a plan file). - Verify the destination now contains that text — re-read the file and confirm the exact text is present — before touching the source.
- Only once verified present at the destination, remove the anchor text from the source file.
If step 3's verification fails for any reason, stop — do not proceed to step 4 for that finding. Report it in the summary as blocked, with the source left untouched. A
movemust never remove content from the source without first confirming it landed at the destination — this is the one failure mode ("silent loss") this skill exists to prevent, and no other consideration in this skill overrides it.
Step 5 — Handle judgment findings, by mode
Before handling any judgment finding, load the settled-judgment memory
(see ## Project memory below) and filter the agent's judgment findings
against it: if a finding's Anchor matches a settled call recorded there and
the anchor text is unchanged since that decision, the user already ruled on
it — drop it silently (do not re-surface or re-defer it). This filtering
applies in both modes. A finding whose anchor text has changed since the
recorded decision is treated as new — the earlier ruling no longer applies to
it.
-
Unattended mode: take no action on any surviving
judgmentfinding. Collect them for the summary (Step 6) as deferred, with their file, Anchor, Issue, and proposed Action, so the calling session can review and act on them later. (Unattended mode records nothing to memory — it settles nothing.) -
Interactive mode (default): present each
judgmentfinding to the user in turn — file, Anchor, Issue, and the agent's proposed Action/Replacement. Ask what to do with it. The default, if the user simply confirms or gives no other direction, is the agent's own proposed Action — itscondensetext, or, for ajudgment+movefinding, the proposed move — but neverdelete. Concretely:- Proposed Action
condense→ apply the finding's Replacement text. - Proposed Action
move→ apply the move, following Step 4'smoveprocedure in full (see the re-verification note below). (Ajudgmentfinding may legitimately be amove; action and gating class vary independently.)
The user may instead choose to delete it, pick a different action, edit the replacement or destination, or leave it as-is. Apply whatever they decide before moving to the next finding.
Whatever action is applied, re-verify the anchor is still present, verbatim, immediately before acting (exactly as Step 4 requires) — an earlier
judgmentfinding just applied to the same file can shift or remove text a later one depends on. For amove, follow Step 4's full four-step sequence — read the destination, write the text, verify it landed, and only then remove the source — including that initial read-the-destination step.The agent's contract forbids it from proposing
deletefor ajudgmentfinding (enforced at Step 3), and this skill will not silentlydeleteone either — a deletion here happens only because the user explicitly asks for it.Record each resolved
judgmentfinding to memory (see## Project memory) as you settle it — whether the user kept it as-is, condensed it, moved it, or deleted it — so a later run does not re-ask about the same call. Record the anchor, the decision, and the date. - Proposed Action
Step 6 — Summary
Report, grouped by outcome:
- Deleted — file and anchor (or a short description) for each.
- Moved — file, anchor, and destination for each, confirming the write-then-remove ordering held.
- Condensed — file and anchor for each.
- Retained —
judgmentfindings left untouched: in interactive mode, ones the user chose to keep as-is; in unattended mode, all of them, listed for later review with enough detail (file, Anchor, Issue) that a future session or/internal-docs-prunerun can act on them without re-reviewing from scratch. - Not applied — any finding skipped for a mechanical reason (anchor not found, incomplete finding, failed destination verification), separate from the categories above since these are not decisions, they are problems.
Step 7 — Commit prefix
This skill does not commit on its own initiative — committing stays
user-gated, per repository convention. If the user asks to commit the
changes this run made (or asks you to prepare a commit message), use the
docs(prune): prefix, e.g. docs(prune): remove duplicated status entries and stale webhook note, so prune commits are discoverable by prefix in
history. If multiple distinct changes happened (e.g. a mechanical
auto-applied pass and a separate user-directed judgment resolution), it's
fine to suggest they be split into more than one docs(prune): commit —
propose the split rather than bundling silently.
Project memory
This skill — not the agent — owns the record of settled judgment calls, so
repeat runs don't re-litigate borderline entries the user has already ruled
on. The agent is stateless and re-reports every borderline call each run; this
skill is the component that holds the user dialogue and therefore the only one
that knows how each call was decided.
Keep a MEMORY.md index at
$CLAUDE_PROJECT_DIR/.claude/agent-memory/devproc-internal-docs-reviewer/
(namespaced under the reviewer agent's name with the devproc- plugin prefix,
so this skill's memory stays distinct from other devproc agents' and skills').
Always resolve the
path against $CLAUDE_PROJECT_DIR (the workspace root), never the current
working directory, so memory lands in the same place regardless of where the
skill is invoked from. Create the directory and file if they do not yet exist;
the first run that settles a judgment call creates them.
Per settled judgment call, record:
- The anchor — file path plus the verbatim anchor text at the time of the decision (so a later run can tell whether the text has since changed).
- The decision made (kept as-is, condensed to X, moved to Y, or deleted).
- The date.
Read this index at the start of Step 5 and use it to suppress already-decided
judgment findings (Step 5's filter). Write to it only when a judgment call
is actually settled — which happens only in interactive mode, since unattended
mode defers rather than decides. Never record redundant or stale findings
here: those are re-verified against the live repository on every run
regardless of past decisions (a duplication or contradiction can newly arise
or newly resolve between runs), so memory must never suppress them.
Idempotency
A second run over files this skill has just pruned should find no new
redundant or stale findings — those are exactly what Step 4 clears. A
residual judgment finding is expected and fine: those are never
auto-resolved, so one a user chose to keep as-is (interactive) or one that
was deferred (unattended) will still be raised by the agent — but if it was
settled in interactive mode, the Step 5 memory filter suppresses it, so it
does not re-bother the user; a deferred (unattended) one, never settled, will
re-surface, which is exactly what "escalated, not silently resolved" means. If
a second run does surface a redundant or stale finding, that is either
newly introduced since the first run (something else changed the file) or a
sign the previous apply pass didn't fully take — investigate rather than
assuming it's expected.
04 同仓库更多 Skills
greet
Greet a person by name using the greeter tool
greet
Greet a person by name using the greeter tool
review-full
暂无简介
review-docs
暂无简介
review-component
Code review scoped to a described component or area — resolves the description to files, then runs simplicity, general, and nitty agents; auto-applies code-level findings until convergence; escalates architectural findings for user confirmation
review-branch
暂无简介