cdd-maintain（CDD 维护）

CDD Maintain (explicit-only)

Use this skill for explicit codebase maintenance: archive long CDD files, audit support-doc drift, propose approval-gated documentation refreshes, and doctor the repo for refactor and dead-code signals.

Sources of truth

Read:

• AGENTS.md
• README.md
• TODO.md and adjacent TODO*.md
• docs/JOURNAL.md
• docs/INDEX.md
• docs/specs/prd.md
• docs/specs/blueprint.md
• docs/prompts/PROMPT-INDEX.md if present
• repo manifests, entrypoints, and test/lint/typecheck config as needed for code-health checks

Safe archive behavior

• Apply safe archive moves immediately.
• Ask before deleting stale adjacent TODO*.md files.
• Do not delete or rewrite application code as part of maintenance.
• Do not silently rewrite support docs as part of maintenance.

TODO archive rules

• Check TODO.md and adjacent TODO*.md files.
• Treat a step as archiveable only when its task list is fully complete under the repo's current TODO style.
• If step completion is ambiguous, leave that step in place and report it.
• Preserve top-to-bottom TODO history: archive only from the oldest contiguous archiveable block near the top of the active step list.
• Never archive a step from the middle or tail of the active TODO file.
• Do not leapfrog an older incomplete or ambiguous step in order to archive later completed steps below it.
• Retain the newest 3 step headings in each active TODO file.
• Archive older completed steps when a TODO file is long enough to need trimming.
• Treat a TODO file as long when it has more than 6 step headings or clearly accumulated completed historical steps beyond the retained active window.
• Move archived sections into docs/archive/.
• Use archive filenames:

- TODO.md -> docs/archive/TODO_YYYY-MM-DD.md - TODO-foo.md -> docs/archive/TODO-foo_YYYY-MM-DD.md

• If the same-day archive file already exists, append the newly archived sections instead of overwriting it.
• If older incomplete or ambiguous steps block a clean top trim, do not archive later completed steps; report archival as blocked by non-contiguous active history.
• After archiving, keep the active TODO file focused on the retained newest 3 step headings plus any older incomplete or ambiguous steps that could not be archived safely.

Stale adjacent TODO file handling

• For adjacent TODO*.md files, check last activity using git log -1 timestamp when available.
• If git history is unavailable, fall back to filesystem mtime.
• If an adjacent TODO file is older than 14 days and has no remaining active work after safe archiving, ask the user once for approval before deleting those stale files.
• Group all such stale-file deletions into one approval request.

Journal archive rules

• Read the archive or rotation guidance at the top of docs/JOURNAL.md.
• Archive docs/JOURNAL.md only according to the rules defined there.
• If docs/JOURNAL.md has no clear archive rule near the top, do not invent one; skip journal archival and report that it was skipped.

Support documentation drift review

• Treat README.md, docs/specs/prd.md, and docs/specs/blueprint.md as canonical support docs.
• Also review docs/INDEX.md and docs/prompts/PROMPT-INDEX.md when present as support-doc navigation surfaces.
• Compare each support doc against the current repo state using manifests, entrypoints, scripts, active TODO/JOURNAL context, and the other support docs.
• Check whether setup/dev/test/build instructions, documented workflows, active features, architecture notes, and referenced doc paths still match the repo.
• Classify each support doc as current, drifted, missing, or unclear.
• If a support doc is missing, report it explicitly and do not fabricate it automatically as part of maintenance.
• If README.md or docs/specs/* has drifted, prepare the needed edits and show them to the user before applying anything.
• Do not silently refresh README.md, docs/specs/prd.md, docs/specs/blueprint.md, docs/INDEX.md, or docs/prompts/PROMPT-INDEX.md.
• Ask once for documentation approval using a single grouped confirmation such as: Approve and apply these documentation updates?
• Keep documentation approval separate from stale TODO deletion approval so the user can approve doc updates without approving file deletions.
• If the user approves, apply only the approved support-doc edits and then report them.
• If the user does not approve, leave support docs unchanged and report the remaining drift clearly.

INDEX freshness

• Check how old docs/INDEX.md is using the last git change when available, otherwise filesystem mtime.
• Report the exact age in days.
• Classify freshness as:

- fresh for 0-14 days - stale for 15-30 days - very stale for over 30 days or clearly older than current TODO or journal activity

Codebase doctoring

• Check the severity of files and areas that appear to need refactoring.
• Use repo-native lint, typecheck, or unused-code tooling when present.
• Otherwise use conservative heuristic scans for:

- orphaned files or modules - dead or unreachable code paths - unused exports or duplicate retired implementation paths - stale feature code that no longer appears wired into entrypoints

• Report findings with both:

- severity: high, medium, or low - confidence: confirmed, probable, or possible

• Never auto-delete code.
• Do not create TODO or refactor files automatically.

Output

Return a maintenance report that includes:

• Archive actions applied
• Deletion approval needed
• Journal archive status
• Support documentation status
• Documentation updates proposed or Documentation updates applied
• Documentation approval needed
• INDEX freshness
• Refactor severity summary
• Dead/orphan code findings
• Recommended next action

Recommend follow-up such as cdd-index, cdd-refactor, cdd-plan, or direct cleanup work when supported by the findings, but do not create those artifacts automatically.