Prune Stale Guidance

Prune Stale Guidance

Remove stale guidance with evidence. Keep only current truth in the working tree and use Git history for obsolete or superseded prose.

Establish Scope and Authority

1. Read every applicable AGENTS.md and repository instruction before editing.
2. Identify the requested files, audiences, and current source of truth.
3. Inspect nearby code, configuration, tests, referenced paths, and newer documentation when they can prove whether text is current.
4. Inspect Git history with git log, git show, and git blame to establish origin, supersession, and deletion safety. Prefer path-specific and line-specific queries.
5. Treat higher-priority instructions, safety boundaries, generated markers, legal notices, compatibility requirements, and externally owned contracts as protected unless the user explicitly scopes them in.

Do not create commits, rewrite Git history, or restore old text unless the user requests it.

Classify Each Candidate

Assign one disposition before editing:

• Delete when the statement is demonstrably obsolete, superseded, duplicated without added value, describes a removed surface, or exists only to preserve history already available in Git.
• Delete the file when its only remaining purpose is an old plan, completed migration, superseded decision, historical snapshot, or archive record. Remove dependent indexes and links in the same pass.
• Repair minimally when the concept remains valid but a name, path, command, version, or narrow fact has changed.
• Consolidate when multiple passages impose the same current rule; retain the clearest authoritative occurrence and preserve necessary exceptions.
• Keep only when the statement is current, a required safety invariant, legally required, or needed by an active compatibility or ownership contract.
• Escalate only when conflicting authoritative sources would make deletion materially risky and code plus Git history cannot resolve them.

Do not preserve obsolete prose merely because it is historically interesting. Do not add retirement notes, migration narratives, changelog-style explanations, tombstones, or archive copies as a substitute for deletion. Git is the default historical record.

If a machine-enforced ownership contract requires a stub, keep only the smallest current pointer required by that contract; remove historical narrative from the stub.

Replace Orphaned Identifiers

Treat an identifier as orphaned when a current reader cannot understand its meaning from the same paragraph or a current canonical source. Typical candidates include G007, US-001, AC-6b, phase/story/gate codes, retired roadmap labels, and bare ticket names.

1. Search the scoped corpus for repeated identifier shapes and build a candidate list. Do not assume every uppercase token is stale.
2. Resolve each candidate from current code and canonical documents first, then use git log -S<identifier>, git log -G<pattern>, git blame, and git show to recover its original meaning and later changes.
3. Identify the present-day semantic fact: the component, action, invariant, precondition, failure mode, decision, or expected result the identifier represented.
4. Replace the identifier with a concise phrase that states that fact directly. Rewrite the surrounding sentence when word substitution would remain awkward or ambiguous.
5. Remove the old identifier entirely when Git is sufficient for historical lookup and no current contract consumes it.

Prefer descriptions such as “the release-backed fleet manifest attestation” or “reject a loop whose resolved workspace has no score file” over codes such as G007 or AC-6b. Use the repository's canonical vocabulary rather than inventing a new expansion.

Keep an identifier only when it remains a current machine key, schema value, CLI/API token, audit artifact field, externally governed issue ID, or tested compatibility surface. In prose, introduce its meaning before or beside it, for example: “the unavailable-simulation fail-safe verdict (sim_unavailable)”. Do not rename machine-consumed values as part of prose cleanup.

If Git history shows multiple incompatible meanings, do not guess. Resolve the meaning from the specific file revision and current implementation, or keep the identifier and report the ambiguity.

Edit Conservatively

1. Form a short cleanup plan before modifying files.
2. Preserve generated/runtime marker pairs and edit inside them only when their ownership contract permits it.
3. Delete stale content instead of moving it into archive/, an archive section, a completed-plan directory, or a historical appendix.
4. Remove dead cross-references, empty headings, orphaned introductions, archive index entries, and duplicated transitions created by deletion.
5. Update directly dependent links, manifests, ownership maps, terminology maps, and indexes in the same bounded pass.
6. Avoid broad stylistic rewrites, new policy, new abstractions, or unrelated cleanup.
7. Preserve the document's language, terminology, formatting, and normative strength for content that remains current.

For executable comments or configuration guidance, lock behavior with an existing or targeted regression test before editing when the text change could conceal a behavior change.

Verify

Run the smallest checks that prove the cleanup is sound:

1. Search for removed names, paths, commands, versions, archive entries, and dangling references.
2. Use git diff to confirm obsolete content was deleted rather than relocated or restated as history.
3. Use git log -- <path> or git show <revision>:<path> to confirm deleted history remains recoverable when needed.
4. Re-read edited sections for grammar, heading structure, and contradictions.
5. Search again for scoped orphaned identifiers. Confirm every remaining occurrence is current, machine-required, externally governed, or explained locally.
6. Validate links, ownership checks, terminology drift checks, documentation tooling, lint, or tests when available and relevant.
7. Confirm protected instructions and generated markers remain intact.

If code and Git history cannot establish that a candidate is stale, keep it and report the uncertainty instead of guessing.

Report

Summarize:

• files changed or deleted;
• what was deleted, minimally repaired, or consolidated;
• which opaque identifiers were replaced and the semantic wording chosen;
• current-state and Git evidence used;
• validation run and any remaining uncertainty.

Do not create a prose archive in the report. Do not claim that all documentation is current unless the inspected scope supports that claim.