file-maintenance

name	file-maintenance
description	Perform an explicitly requested repository file-hygiene review or maintenance pass focused on factual accuracy, freshness, consistency, and duplicate or stale file prevention; read-only audits do not authorize corrections.

File Maintenance

Quick Index (Action-Routed)

Read First (All Actions)

1. Mission
2. Use This Skill When
3. Scope Boundary
4. Core Principles

Action Modules (Read As Needed)

1. Accuracy maintenance:
   • File Integrity Audit
   • Factuality and Freshness Checks
2. Consistency maintenance:
   • Cross-File Consistency Rules
   • Duplicate and Staleness Control
3. Documentation maintenance depth:
   • Doc Accuracy Standard
   • Operational Validation

Output

1. Deliverable Format
2. Anti-Patterns

Mission

Maintain repository files so they remain accurate, current, internally consistent, and actionable for developers and operators.

Authority and Artifact Policy

1. Activating this skill grants no authority to correct, consolidate, move, archive, or delete files.
2. A read-only maintenance audit may identify and prioritize findings without changing repository state.
3. Apply corrections only when the task separately authorizes the affected files and operations.

Use This Skill When

1. documentation or policy files may be stale after changes
2. duplicate files or conflicting variants appear
3. commands/examples in docs might no longer match implementation
4. periodic file hygiene reviews are requested
5. quality audits require factuality and consistency checks

Scope Boundary

This skill governs ongoing file lifecycle quality across docs and support artifacts.

Use Doc Maintenance for:

1. change-driven documentation updates during active implementation

Use File Structure Optimization for:

1. repo layout and directory architecture optimization

Core Principles

1. every maintained file must have a clear purpose and current owner context
2. prefer one canonical source per fact
3. stale or conflicting files must be corrected, consolidated, or removed
4. documentation claims require validation evidence
5. maintenance outputs must be auditable

Anti-Overuse Rules

Use when:

1. the task is a file hygiene, factuality, freshness, or consistency audit
2. duplicate or stale documents may conflict
3. public docs or policy files need cross-file validation

Do not use when:

1. a single canonical doc is being updated as part of implementation
2. no file-hygiene audit or maintenance outcome is in scope
3. doc-maintenance already covers the necessary change-driven doc update

Stop after:

1. stale/conflicting files are corrected or explicitly tracked
2. canonical sources are identified
3. unresolved findings have owner, severity, and next action

File Integrity Audit

Audit file surfaces for:

1. purpose clarity
2. last-updated relevance
3. duplicate/conflicting variants
4. broken references/paths/commands
5. ownership ambiguity

Factuality and Freshness Checks

For high-value docs/artifacts:

1. verify dates, versions, and commands are still valid
2. verify referenced paths/files exist
3. verify procedures match current behavior
4. verify policy statements match enforced tooling
5. mark unresolved uncertainty explicitly

Cross-File Consistency Rules

1. same concept should not be described differently across canonical docs
2. terminology must be consistent across policy/runbook files
3. sample commands must align with current scripts
4. linked artifacts must exist and be reachable
5. if conflicts exist, designate canonical source and reconcile others

Duplicate and Staleness Control

1. detect duplicate files with overlapping scope
2. consolidate into canonical file where feasible
3. archive/remove obsolete copies with explicit notes when needed
4. avoid keeping "backup" duplicates in active source paths
5. track unresolved cleanup items with owner and date

Doc Accuracy Standard

For docs in scope, ensure:

1. statements are specific and testable
2. instructions are executable in current repo context
3. references use current filenames and paths
4. temporal language is minimized unless date-bound context is required
5. update timestamps/status artifacts reflect latest state

Operational Validation

Recommended validation pass:

1. targeted command execution or plausibility check
2. link/path existence scan
3. policy-to-enforcement alignment check
4. issue list of remaining uncertain claims

Acceptance Checklist

1. no unresolved high-severity factual conflicts
2. no broken high-priority file references
3. stale duplicates addressed or tracked with explicit remediation
4. docs/policies aligned with actual tooling behavior
5. maintenance evidence captured

Deliverable Format

When applying this skill, provide:

1. files audited and findings
2. corrections/consolidations/removals made
3. validation checks run and outcomes
4. unresolved items with severity and next action

Source Reference

Primary references:

1. Google developer documentation style guidance:
   • https://developers.google.com/style/
   • https://developers.google.com/style/timeless-documentation
2. Apple documentation workflow guidance:
   • https://developer.apple.com/documentation/xcode/writing-documentation
   • https://developer.apple.com/documentation/xcode/documenting-apps-frameworks-and-packages
3. MIT software construction quality principles:
   • https://ocw.mit.edu/courses/6-005-software-construction-spring-2016/

Anti-Patterns

1. leaving known inaccuracies untracked
2. keeping multiple conflicting "source of truth" files
3. updating content without validating commands/paths
4. burying critical caveats in non-canonical docs
5. treating file hygiene as optional after major changes

Related Skills

• Doc Maintenance: implementation-time documentation synchronization.
• File Structure Optimization: repository architecture hygiene.
• User Instructions Tracker: track directive-driven maintenance obligations.
• Governance Enforcement: validate policy-file correctness through tooling.
• Artifact Budget Enforcement: keep cached artifacts and tables from growing without limits.