durable-artifact-cleanup

name	durable-artifact-cleanup
description	Audit and remove obsolete durable implementation artifacts after execution is complete.

Durable Artifact Cleanup

Use this skill when source docs, implementation handoffs, improvement records, plans, execution-state docs, or handoff prompts have served their purpose and should not drift from maintained code.

Contract

Scope boundary:

• This is the audit and policy workflow for cleanup.
• When plan-tooling artifact-audit is available, use it for repeated candidate classification into delete, keep, rehome, and manual-review.
• Helper output is advisory. This skill still owns policy interpretation, retained-evidence judgment, and final deletion approval.
• When the helper is unavailable, perform the same classification manually with repo-local evidence and dry-run review.
• For broad docs/plans/ batch deletion, use this skill to classify ambiguous scope first, then use docs-plan-cleanup as the deterministic batch executor when keep/delete intent is known.

Prereqs:

• User explicitly asks to audit, prune, delete, or clean up durable implementation artifacts.
• Target workspace is a git work tree and project rules allow documentation cleanup after required preflight.
• Candidate artifacts are known or discoverable from source document, execution-state document, docs index, issue, PR, or user-provided path.
• Run an audit/dry-run classification before deletion; apply deletion only after the user asks for cleanup or has already authorized it.

Inputs:

• Candidate artifact paths, docs folder, source document, execution-state document, plan path, issue/PR link, or user-described cleanup scope.
• Optional completion evidence such as merged PR, closed issue, Status: complete, passing validation, final commit, or accepted-risk note.
• Optional keep/delete preferences, retention rules, docs index path, and validation commands.

Outputs:

• Cleanup report grouping artifacts as delete, keep, rehome, and manual-review.
• Deleted obsolete durable artifacts only when the audit shows they are complete, unreferenced, and safe to remove.
• Updated docs index or README when removed artifacts were listed there.
• A concise response listing deleted files, retained files, validation, and any unresolved cleanup risks.

Exit codes:

• N/A (conversation/workflow skill)

Failure modes:

• Candidate artifact is still active, blocked, in progress, or lacks clear completion evidence.
• Candidate is still referenced by source docs, plans, issues, PRs, code comments, tests, README/index files, or execution state.
• Artifact contains retained evidence, diagnostic history, raw run output, or compliance/audit material that project policy requires keeping.
• Artifact is a HEURISTIC_SYSTEM error inbox or operation record that is still open, promoted, or retained as durable evidence.
• Cleanup scope mixes obsolete durable docs with runtime fixtures, generated outputs, raw logs, or test evidence; split the scope first.
• Deletion would leave dangling links or remove the only source for acceptance, validation, or decision history.

Workflow

1. Confirm cleanup scope

   • Identify whether the candidates are implementation handoffs, improvement records, plans, execution-state docs, handoff prompts, or related evidence.
   • Classify source docs, plans, and execution-state docs as one execution bundle when they live together under docs/plans/<slug>/ and none has been promoted into maintained docs.
   • Prefer plan-tooling artifact-audit --candidate <path> --format json when multiple candidates or repeated classification are involved. Treat the JSON classes as input to this workflow, not as authority to delete files.
   • If plan-tooling artifact-audit is not installed or cannot evaluate the repository, continue with the manual audit steps below and report the fallback.
   • Use this workflow for named artifacts or unclear cleanup status. Use docs-plan-cleanup for broad docs/plans/ pruning after active bundles are known.
   • Treat deletion as the preferred end state for obsolete durable docs once they are complete and unreferenced.
   • Use rehome only when the project has audit, release, compliance, or historical lookup needs.

2. Verify completion

   • Read candidate docs and their execution state.
   • Confirm Status: complete, equivalent task ledger completion, merged/closed issue or PR, or explicit user confirmation.
   • If open questions, blockers, incomplete validation, or active tasks remain, classify the artifact as keep or manual-review.

3. Scan references

   • Use rg over tracked docs/code/tests plus relevant issue/PR links when available.
   • Check docs indexes, README files, Read First lists, execution-state links, plan references, and handoff prompts.
   • If a sibling source doc, plan, or execution-state doc still points at the candidate, either keep the bundle together or update the maintained reference before deletion.
   • Classify candidates still referenced by maintained material as keep or rehome until references are updated.

4. Separate evidence from stale coordination docs

   • Do not delete retained evidence, redacted validation artifacts, diagnostic logs, or raw run outputs unless the user explicitly asks and project retention rules allow it.
   • Treat heuristic-system/error-inbox/ and heuristic-system/operation-records/ as retained evidence locations. Keep them unless the entry is closed/promoted and the cleanup request explicitly includes it.
   • Do not mix cleanup of durable docs with cleanup of runtime fixtures or generated build/test outputs.
   • If evidence is useful but the coordination doc is stale, classify it as rehome until the retained content is linked from a maintained location.

5. Apply cleanup

   • Delete only artifacts classified as delete.
   • For broad docs/plans/ cleanup, run docs-plan-cleanup dry-run/execute instead of manually deleting plan bundles.
   • Update docs indexes, README files, and source documents so links do not dangle.
   • If deletion creates empty docs folders, remove them only when project rules allow it.
   • Keep changes scoped to cleanup; do not refactor the docs tree unless asked.

6. Validate and report

   • Run the smallest project-appropriate docs checks, usually markdown lint, docs freshness, and link/reference checks.
   • Report deleted paths, retained paths, updated indexes, validation commands, and any manual-review items.
   • If validation fails, stop and report the failing command instead of claiming cleanup complete.

Relationship To Nearby Skills

• discussion-to-implementation-doc: creates implementation handoffs that may later become cleanup candidates.
• review-to-improvement-doc: creates improvement records; delete them only after fixes are complete and evidence is retained elsewhere when needed.
• execute-from-plan: updates execution state; use this cleanup skill after execution status is complete and no future resume is needed.
• docs-plan-cleanup: deterministic batch executor for broad docs/plans/ coordination-doc pruning with its existing report format. Use it after this workflow or a reviewed plan-tooling artifact-audit report when keep/delete intent is known.
• handoff-session-prompt: prompt artifacts should usually be deleted once source docs and execution state are the maintained record.