tidy-repo

Skill: Whole-Repository Cleanup

Purpose

In a single run, scan the directory structure of the repository (or a specified scope), identify structural problems—misplaced files, naming inconsistencies, empty directories, stale artifacts, duplicate entries—and output aprioritized cleanup report, to guide manual or automated cleanup. In apply-safe mode, safe, reversible operations can be executed directly.

---

Core Objective

Governance objective: Generate a repository cleanup report in which (1) all structural problems and recommended actions are listed in a standard format, (2) specific cleanup steps are given, ordered by impact and cost, and (3) optionally, in apply-safe mode, operations are executed and an operation log is recorded.

Success criteria(all requirements must be met):

1. ✅ Scope determined: Clearly define the scan root path and exclusion list (.git、node_modules、.venv , etc.)
2. ✅ Problems enumerated: All findings are output in a standard format (location, category, severity, title, description, recommendation)
3. ✅ Priorities ordered: Ordered by impact (high|medium|low) and operational cost (small|medium|large)
4. ✅ Cleanup plan actionable: Each step includes specific paths, operation type, and completion conditions
5. ✅ Safety boundaries observed：report-only mode does not modify any files;apply-safe only performs reversible operations
6. ✅ Report persisted: Written to the agreed path, including compliance prerequisites

Acceptance test: Can the team, using only the first 5 actions in this report, achieve a significant improvement in repository structure? If not, reduce ambiguity and strengthen prioritization.

---

Scope Boundaries

This skill is responsible for：

• Enumerating and analyzing repository file and directory structure
• Identifying: misplaced files, naming inconsistencies, empty directories, stale/deprecated artifacts, duplicate entries
• Outputting a standard-format findings list by category and severity
• Generating a prioritized cleanup plan
• (Optional) In apply-safe mode, executing reversible operations such as moving and deleting empty directories, and logging them

This skill is not responsible for：

• Code quality or architecture issues → review-codebase
• Documentation standards compliance → assess-docs
• Content quality of requirements or planning documents → align-planning
• Dangerous operations (bulk deletion of non-empty directories, modifying git history, etc.) → manual execution
• Committing the cleaned-up changes → commit-work

Handoff points: After the report is delivered, the commit operation can be handed off to commit-work; if documentation standards issues are found, hand off to assess-docs; if architecture issues are found, hand off to review-codebase。

---

Use Cases

• Routine maintenance: Periodic structural health checks after files accumulate in the repository
• Onboarding alignment: When new members join, quickly understand and align on directory conventions
• Post-refactoring cleanup: After code refactoring or module splitting, remove leftover old paths and deprecated files
• CI/CD gating: As a structural compliance check step in the pipeline
• Pre-release cleanup: Ensure the repository is tidy before a version release

---

Behavior

Phase 0: Norms Resolution (new in v1.3)

Per specs/artifact-contract.md §8 Runtime Norms Resolution Protocol §8.2 / §8.3 / §8.5 implementation: read the project spec if it declares the repo-tidy artifact_type's path_pattern, then use the project value; otherwise fall through to the skill default (docs/calibration/repo-tidy.md). This skill is afixed-path governance output, and only uses the path_pattern override mechanism; the tidy operation itself respects the artifact path_pattern declared by the project (moving files to the location specified by the project rather than the AI Cortex default).

Interaction policy

• Preconditions: the project must have a documentation spec (new)
• Default mode：report-only, does not modify any files
• apply-safe mode: confirm the operation list with the user before execution; on failure, roll back the steps already executed
• Scope: by default scan the current working directory; exclude .git、node_modules、.venv、dist、build、__pycache__、.DS_Store etc.

Precondition check (new)

Purpose: ensure the project has established a documentation spec, so that naming and path issues can be detected accurately

Checks：

1. Look for docs/ARTIFACT_NORMS.md
2. If it does not exist,refuse to continueand output:

   ✗ 找不到文档规范
   
   tidy-repo 需要项目先建立文档规范来准确检测文件位置和命名问题。
   
   请先运行：
   /discover-docs-norms
   
   此命令将：
   - 扫描现有 docs/ 结构
   - 推导出项目的命名和路径约定
   - 生成 docs/ARTIFACT_NORMS.md
   
   然后重新运行 tidy-repo。
   

Phase 0: Scope resolution

1. Resolve the repository root path (default CWD) and optional scope filters
2. Force-loadproject conventions (precondition already verified to exist): from docs/ARTIFACT_NORMS.md parse naming rules and directory structure expectations
3. Build the exclusion list (binary file directories, dependency directories, build artifact directories)

Phase 1: Structure scan

1. Recursively enumerate all files and directories (following the exclusion list)
2. Build a directory tree snapshot, recording: path, type (file|directory), size, last modified time, extension

Phase 2: Issue detection

For each entry, detect by the following categories:

Category	Detection logic
misplaced	The directory where a file resides does not match its type/content (e.g. .md in src/，.py in docs/）
naming	File or directory names violate project conventions (case, separators, inconsistent prefix/suffix)
empty-dir	The directory contains no valid files (only .gitkeep excepted)
dead-artifact	Obviously abandoned files (extension is .bak、.tmp、.orig; name contains DEPRECATED、OLD、UNUSED; unmodified for over 180 days and unreferenced)
duplicate	File names or paths are highly similar, suspected duplicates (e.g. util.py and utils.py in the same directory)
structure	Unexpected directories appear at the top level, or the agreed standard directories are missing (e.g. docs/、src/）
root-categorization	Files in the docs/ root directory should be categorized into subdirectories (there should be nothing except index and governance files)
naming/timestamp-misuse	File names contain unnecessary or malformed timestamps (only for types that do not allow timestamps)

Root-Categorization detection details：

1. From docs/ARTIFACT_NORMS.md read the allowed root directory file list (index files, governance files)
2. Scan docs/ all .md files in the root directory
3. For each .md file:
   • If it matches the allowlist (README.md, INDEX.md, ARTIFACT_NORMS.md, etc.) → skip
   • Otherwise, infer its artifact_type (from front-matter, filename, content)
   • Look up the path_pattern for that type in ARTIFACT_NORMS.md
   • Create finding:root-categorization, suggest moving to that directory, severity:suggestion(info level)
4. Example:docs/goals.md → inferred type is goals → look up the norm → suggest moving to docs/goals/goals.md

Timestamp-Misuse detection details(new):

1. From docs/ARTIFACT_NORMS.md read the timestamp policy
2. For each .md file:
   • Check whether the filename has the YYYY-MM-DD prefix
   • Infer its artifact_type
   • Look up whether that type allows timestamps
   • If the filehas atimestamp but the typedoes not allow it → create finding:naming/timestamp-misuse, suggest removing the prefix
   • If the filedoes not have atimestamp but the typerequires it(adr, design-decision) → create finding:naming/timestamp-missing(optional)
   • If there is a timestamp but the format is wrong (e.g. 2026/03/15) → suggest the correct format:YYYY-MM-DD
3. Example:docs/requirements-planning/2026-03-15-api-requirements.md → inferred type is requirements → look up the norm → suggest renaming to api-requirements.md

Phase 3: Findings output

Each finding must follow the standard format:

Field	Content
Location	path/to/file-or-dir
Category	misplaced | naming | empty-dir | dead-artifact | duplicate | structure | root-categorization | naming/timestamp-misuse
Severity	critical | major | minor | suggestion
Title	Brief issue summary
Description	Specifically explain what is wrong
Suggestion	Specific action (e.g. "move to X", "rename to Y", "delete empty directory", "confirm whether deprecated, then delete")

Summary: total files scanned, total directories, number of findings by category, number of findings by severity.

Phase 4: Prioritization

Evaluate each finding:

• Impact(high|medium|low): degree of obstruction to navigability, CI, and new-member onboarding
• Action cost(small|medium|large): effort to carry out the suggested action

Prioritization principle: handle high-impact, low-cost issues first (quick wins); next high-impact, high-cost (requires planning); finally low-impact issues (optional).

Phase 5: Cleanup plan

Output the minimal actionable step set:

Each step includes:

• Action path
• Action type (move | rename | delete-empty-dir | archive | review-manually）
• Reason (Why now)
• Completion condition
• Whether it can be automatically executed in apply-safe mode

Phase 6 (optional): apply-safe execution

Activated only when the user explicitly passes apply-safe mode:

1. Show the user the list of operations to be performed and wait for confirmation
2. Perform only the following safe operations:
   • Move/rename files (git mv Priority)
   • Deleteempty directory
3. Skip (and mark as "needs manual handling"):
   • Delete non-empty directories
   • Overwrite existing files
   • Any irreversible operation
4. Record an operation log, appended to the end of the report

Phase 7: Persist the report

Write path (per project conventions or default docs/calibration/repo-tidy.md). Report prerequisites:

artifact_type: repo-tidy
created_by: tidy-repo
lifecycle: living
created_at: YYYY-MM-DD

---

Inputs & Outputs

Inputs

• Repository root path (default CWD)
• Optional scope filter (subdirectory or glob)
• Optional mode:report-only(default) | apply-safe

Outputs

---
artifact_type: repo-tidy
created_by: tidy-repo
lifecycle: living
created_at: YYYY-MM-DD
---

# Repository Tidy Report

**Date:** YYYY-MM-DD
**Scope:** /path/to/root (filtered: src/)
**Mode:** report-only | apply-safe
**Summary:** N files, M dirs scanned; K findings (critical: X, major: Y, minor: Z, suggestion: W)

## Findings

| Location | Category | Severity | Title | Description | Suggestion |
| :--- | :--- | :--- | :--- | :--- | :--- |
| src/utils.bak | dead-artifact | major | Backup file in source | .bak file committed to source tree | Remove or archive to .archive/ |

(If no findings: "No structural issues found.")

## Cleanup Plan

### Quick Wins (high impact, low effort)

1. **Path:** src/utils.bak
   **Action:** delete
   **Why now:** Dead artifact pollutes source tree
   **Done condition:** File removed; no references in codebase
   **Auto-apply:** yes

### Plan Next Sprint (high impact, high effort)

...

### Optional / Low Priority

...

## Apply Log (apply-safe mode only)

| Action | Path | Result |
| :--- | :--- | :--- |
| delete-empty-dir | tmp/ | success |
| move | docs/OLD-arch.md → .archive/OLD-arch.md | success |
| skipped (manual) | src/legacy/ | non-empty directory — review manually |

## Machine-Readable Summary

    scope: "."
    mode: "report-only"
    filesScanned: 142
    dirsScanned: 28
    findings:
      total: 7
      bySeverity: { critical: 0, major: 3, minor: 2, suggestion: 2 }
      byCategory: { misplaced: 1, naming: 2, empty-dir: 1, dead-artifact: 2, duplicate: 1 }
    topActions:
      - { path: "src/utils.bak", action: "delete", impact: "high", effort: "small" }

---

Constraints

Hard Boundaries

• report-only modenever modifyany file or directory
• apply-safe modenever deletenon-empty directories; all dangerous operations are marked as "needs manual handling"
• Do not fabricate or speculate about file contents; judge only based on path, name, modification time, and size
• Do not modify git history
• Do not perform any network operations

Skill Boundaries

Do not do (handled by other skills)：

• Code quality, architecture, dependency review → review-codebase
• Documentation content standards and readiness → assess-docs
• Requirements/planning document alignment → align-planning
• Commit cleanup results → commit-work

When to stop and hand off：

• If a large number of documentation standard violations are found → hand off to assess-docs
• If cleanup changes need to be committed → hand off to commit-work
• If architecture-level issues are found → hand off to review-codebase

---

Self-Check

Core success criteria (all criteria must be met)

• scope is clear; exclusion list has been applied
• all findings are output in the standard format (location, category, severity, title, description, recommendation)
• findings are sorted by impact and cost
• the cleanup plan includes specific paths and operation types
• apply-safe mode performs only reversible operations and records an operation log
• the report has been written to the agreed path and includes the compliance prerequisites

Process quality checks

• no low-impact issues are falsely reported as high severity
• recommended operations are specific and directly executable
• handoff skill names are valid and up to date

Acceptance test

Can the team, using only the top 5 actions in the report, achieve a significant improvement in repository structure?

If not: reduce ambiguity and strengthen prioritization and specificity. If yes: the report is complete.

---

Examples

Example 1: Discovering an abandoned artifact

• File:src/auth.py.bak, unmodified for 7 months
• Finding: location src/auth.py.bak, category dead-artifact, severity major, title "Backup file in source directory", description ".bak file was committed into the source tree", recommendation "Delete or move to .archive/"
• Cleanup plan: Quick Win;apply-safe can be executed automatically

Example 2: Empty directory

• Directory:tmp/cache/(no files at all)
• Finding: Category empty-dir, Severity minor, Recommendation "Delete the empty directory, or add .gitkeep if you intend to keep it"
• apply-safe Mode: Auto-delete

Example 3: Inconsistent Naming

• Finding:src/ contains both UserService.py(PascalCase) and auth_service.py（snake_case）
• Severity:major, Recommendation "Unify the naming convention; refer to the project's existing dominant style to decide the direction of renaming"
• Mark as "Needs Manual Handling" (renaming involves updating import references)

Example 4: apply-safe Execution Log

已执行：delete-empty-dir tmp/cache/        ✓
已执行：move docs/OLD-arch.md → .archive/ ✓
已跳过：src/legacy/（非空目录，需人工处理）

---

Appendix: Output Contract (Appendix: Output Contract)

This skill produces a Tidy Report:

Element	Format	Required Fields	Path Pattern
Report Body	Markdown	front-matter; sections: Summary / Misplaced Files / Naming Violations / Empty Directories / Stale/Dead Files / Duplicates / Priority List	docs/calibration/repo-tidy.md
Finding Entry	List Item	category / path / evidence / severity / suggested_action（move/rename/delete/archive）/ effort_estimate	Each category section
Priority List	Table	rank / action / target_path / risk_level / safe_to_auto_apply（bool）	"Priority List" section