Repository Layout and Docs Auditor

Organize Skill

Audits a repository's layout and its project documentation against one set of conventions, using nine detectors, a plan file, and approval by group, and then hands off to /commit or /ship.

References

• references/conventions.md: the target state the detectors check against. It covers naming, layout, reusable versus project code, the documentation model, the current-state rule, superseded content, and the .gitignore categories.

Core Principles

• Plan before acting. Write every finding and every proposed operation to the plan file. Change no file until the user has approved the group that contains it; the one exception is a group labeled "fixes a written rule" (see Plan file), which is applied without asking.
• Take each answer from its source. Disk and git ls-files decide what exists; the project's docs decide what a thing is for and which project rules hold; conventions.md decides what a thing is called and how it is laid out wherever the project's docs state no rule. List every mismatch between these sources in the plan; the user decides which side changes, except in a group labeled "fixes a written rule". Where a rule written in the project's docs conflicts with conventions.md, follow the project rule and list the conflict as a note.
• Ask for approval per group. The user approves or rejects each group of operations in the plan. A clear violation of a rule already written in the project's own docs is fixed without asking. New files and consolidations of duplicated content always wait for approval.
• List every move and deletion for approval. Every move and every deletion appears in the plan as its own operation, and none is applied before the user approves it.
• Edit project documentation only. Among Markdown files, edit only those whose job is describing the repository. Deliverable prose is outside this skill; see Scope.
• Move files safely on synced paths. Copy the file or folder with retry, confirm the copy, then remove the source. Never rename a folder in place on a cloud-synced path such as Dropbox, OneDrive, or iCloud. Let git detect renames after the move; do not use git mv. A rename that changes only case uses the same method twice, through the temporary name that detector A gives.

Workflow

With the argument audit, or when the user asks for an audit only, stop after Step 4 and leave the open questions in the plan file unasked.

Plan file

The plan file has seven sections, in this order:

1. Context: what started the pass, what the repository holds, and the path scope, if any.
2. Findings: grouped under the detector letters A to I, each with its path and the line or name at issue. A note is a finding listed for the user with no operation proposed. Notes stay in Findings and are not repeated under Out of scope.
3. Operations: numbered and grouped for approval. Each group lists its moves, deletions, git rm --cached calls, and documentation edits. A documentation edit shows the old and the new text. A new file, such as a missing README, is drafted in full. Each move or rename carries, in the same group, the edit to every project document that names the old path, and to any note in the project's memory folder (~/.claude/projects/<project>/memory/*.md) that names it.
4. Out of scope: each finding that will not be acted on, with the reason.
5. Open questions: each decision the audit cannot settle, with what the answer changes.
6. Verification: the checks from Step 7 that apply to this plan.
7. Rollback: how to reverse each group. A deleted tracked file or an edited document comes back with git checkout HEAD -- <path> before a commit; a path untracked with git rm --cached is tracked again with git add <path>; an archived folder moves back from _archive/.

An operations group reads like this:

### Group 2: superseded generations (detector B), needs approval

2.1  delete   report_v1.md                         tracked; report.md is current
2.2  move     outputs/models/run_2026-04-14/  ->  outputs/models/_archive/run_2026-04-14/
2.3  edit     outputs/README.md, line 12
     old: "Results are in run_2026-04-14/ and run_2026-05-02/."
     new: "Results are in run_2026-05-02/."

Label each group "needs approval" or "fixes a written rule". Use the second label only for a group of documentation edits with no move, deletion, new file, or consolidation, and that removes no information: no sentence, clause, finding, or recorded reason that the edit does not restate as a current fact; give the file and line where the project states the rule.

Detectors

Run every detector over the whole tree, gitignored paths included, and record each finding in the plan file under its letter. The target state that each detector checks against is in references/conventions.md.

A. Name drift

• Looks for: folder and file names that break conventions.md § Naming, and names that differ in case or spelling between the docs and disk.
• Verify: compare git ls-files and a walk of the disk against every name the root map and the READMEs give.
• Resolve: propose the rename and the matching docs edit as one operation. On a case-insensitive filesystem, rename in two steps through a temporary name (Data/ to data_tmp/ to data/) so that git and the sync client both record the change. When a name lacks part of its date, list it under Open questions instead of proposing a name.
• Never flag: names that conventions.md § Naming writes in capitals (files a tool reads by a fixed name, owner files, and acronyms the project's docs write in capitals), or a name that follows a naming rule written in the project's docs (list the conflict with conventions.md as a note).

B. Superseded generations

• Looks for: folders named v1/, v2/, old/, backup/, bak/, deprecated/, or legacy/; siblings named <name>_old, <name>_backup, <name>_v1, or <name>_v2; dated siblings of current content; and a plan or design document whose work is complete, that describes no part of the current project, and that no current doc points to. Search everywhere outside _archive/, including inside gitignored paths such as outputs/.
• Verify: for dated siblings, apply the test in conventions.md § Superseded content: a sibling is superseded only when the docs and scripts read the later one alone. Diff each remaining candidate against the current folder beside it; when it holds the current content under a wrong name, propose a rename, not a removal.
• Resolve: delete the old version or move it to _archive/, following the tracking split in conventions.md § Superseded content.
• Never flag: anything already inside _archive/, or dated siblings that form a collection under conventions.md § Superseded content. List received material that the docs mark as superseded as a note.

C. Orphan files

• Looks for: files outside gitignored paths whose name and path appear in no root map, README, script, or tracked Markdown file, and which do not sit inside a folder that the root map or a README describes; and files at the root that conventions.md § Layout does not allow, listed as a note when gitignored.
• Verify: search for the basename and the relative path across git ls-files '*.md' and the scripts (*.py, *.R, *.sh, *.js, *.ts). Then check the file's own folder; the file counts as covered when the root map or a README describes that folder. A covered file that nothing names, in a folder whose README has a file table that omits it, is a note.
• Resolve: propose a destination among the existing folders based on file type, or ask the user what the file is for. Never delete an orphan without approval.
• Never flag: files a tool reads by a fixed name and owner files, as conventions.md § Naming defines them, or deliverables.