dotfiles/claude/skills/audit/SKILL.md

name, description, argument-hint

name	description	argument-hint
audit	Scan thinking folder and Obsidian vault inbox for organizational drift — loose files, missing metadata, stale items, broken references. Reports only; never acts without approval.	[thinking|inbox] [--include-deferred]

Collections Audit

Scan the thinking folder and/or Obsidian vault inbox for organizational drift. Produce a structured report of what's out of place. Propose fixes but never execute without explicit steward approval.

Paths

• Thinking folder: /Users/davidglidden/_Dev/CapableMind-AI/docs/thinking/David/
• Thinking README (living index): /Users/davidglidden/_Dev/CapableMind-AI/docs/thinking/README.md
• CURATION-MAP: /Users/davidglidden/_Dev/CapableMind-AI/docs/thinking/David/l2-constitution/CURATION-MAP.md
• Vault root: /Users/davidglidden/Library/Mobile Documents/iCloud~md~obsidian/Documents/David, root-and-branch/
• Vault inbox: 00a. _inbox/ (relative to vault root)
• Vault People: 03. People/ (relative to vault root)

Scope

Parse $ARGUMENTS to determine scope:

• No argument or all → audit both targets
• thinking → thinking folder only
• inbox → vault inbox only

Procedure

1. Thinking Folder Audit

Run these checks in parallel where possible. For frontmatter checks, read only the first 5 lines of each file (check for --- opener), never the full content.

a. Loose files at root

Glob for *.md, *.json, *.yaml directly in the thinking folder (not recursive). Exclude CLAUDE.md (belongs at root by convention). Every other file is a MOVE issue.

Propose destinations using naming heuristics:

• amendment-* → amendments/
• substrate-governance-* → l2-constitution/ (governance inquiry content)
• l2-design-* → l2-constitution/
• D.Glidden - The Chamber* → chamber/ or reviews/
• entities.json, mempalace.yaml → flag for steward decision (utility files, no obvious home)

b. Missing YAML frontmatter

For every .md file across all subdirectories, check if line 1 is ---. This is a binary check — has frontmatter or doesn't. Report as aggregate per subfolder: "N of M files in l2-constitution/ lack frontmatter."

Do NOT propose specific fields — that's an editorial decision for the steward.

c. CURATION-MAP inventory drift

Read CURATION-MAP.md. Extract any file count statistics (§6 or similar). Compare against actual filesystem counts for l2-constitution/ and its subdirectories. Report mismatches.

Also check: are there files on disk in l2-constitution/ that appear in no CURATION-MAP section? These are "uncharted" files.

d. CURATION-MAP §4 — unresolved ambiguous items

Read CURATION-MAP.md §4 (Ambiguous Status). List any items still awaiting steward classification. These are AMBIGUOUS issues — the audit surfaces them but cannot resolve them.

e. Broken cross-references

Grep for markdown links [...](...) that reference .md files within the thinking folder. For each, check if the target file exists (resolving relative paths from the source file's location). Report broken links with source file and line number.

Keep this check scoped to l2-constitution/ (the largest and most cross-referenced subfolder) to stay fast. Expand scope in v2 if needed.

f. README.md drift

Read thinking/README.md. Find David's section. Extract the file counts from subsection headings (pattern: ### Category (Path/) — N files). Compare against actual file counts in each subdirectory. Report mismatches.

2. Vault Inbox Audit

Run these checks in parallel. Read only frontmatter (first 10 lines) of each inbox file.

a. Empty or placeholder titles

Read frontmatter of each .md file in the inbox. Flag files where the title: field is:

• Empty or whitespace-only
• ---, ***, ----, or similar punctuation-only
• A single character or bracket expression like [pattern template]

These are MISSING issues — the file can't be triaged without a usable title.

b. Person-name detection

Identify files whose title: looks like a person or business name: 2–3 capitalized words, no markdown characters, no common sentence starters. Cross-reference against filenames in 03. People/.

• Match found in People → skip (already handled)
• No match → MOVE issue: "Looks like a contact — propose creating People file or routing to 03. People/"

c. Staleness by age

Extract created or draft_created date from frontmatter. Bucket files by age:

• 30–90 days
• 90–180 days
• 180+ days

Report as aggregate with count per bucket: "54 files older than 180 days (Sept 2025 Drafts migration batch)." Do NOT list every file individually — at 67+ files that's noise, not signal.

d. Missing type classification

Count how many inbox files have a type: field in frontmatter. Report the aggregate: "0 of 67 files have type classification."

If the count is low, note the proposed convention for steward consideration:

Proposed type: values: contact, fragment, prompt, session, reference, pedagogy, admin

This is INFO severity — a convention proposal, not an error.

3. Compile Report

Structure the output exactly as follows:

## Audit Report — [date]

**Scope:** [thinking | inbox | both]
**Files scanned:** X thinking, Y inbox
**Issues found:** N

### MOVE (wrong location)
[one line per file: path → proposed destination]

### MISSING (metadata gaps)
[aggregates per subfolder for frontmatter; individual items for titles]

### STALE (drift / aging)
[CURATION-MAP mismatches, README drift, inbox age buckets]

### AMBIGUOUS (needs steward decision)
[CURATION-MAP §4 items, utility files with no obvious home]

### BROKEN (integrity)
[broken cross-references: source file:line → missing target]

### INFO
[type classification proposal, other non-actionable observations]

Omit any section that has zero items. End with:

Approve all proposed moves? Or review individually?

4. Handle Steward Response

If "approve all":

• Execute MOVE items: use git mv for thinking folder files (inside git repo), regular mv for vault files
• After moves in thinking folder: update thinking/README.md per the CLAUDE.md convention (scan filesystem, update file counts in subsection headings)
• Do NOT batch-approve AMBIGUOUS items — those always require individual decisions

If "review individually":

• Present each MOVE item one at a time
• For each: steward says apply / skip
• After all reviewed, execute approved moves and update README

After execution:

• Report what was moved and what was skipped
• Note any AMBIGUOUS items still unresolved

Important constraints

• Never move files without approval. This is a reporting tool first.
• Never read full file contents for the audit scan — frontmatter and filenames only. Content is the steward's domain.
• Respect the iCloud path. The vault path contains spaces. Always quote paths in Bash commands.
• Git awareness. The thinking folder is inside a git repo. Use git mv for moves there. The vault is NOT in a git repo.
• Don't propose content changes. Missing frontmatter is reported; what fields to add is the steward's decision.
• Aggregate where possible. 67 individually listed inbox files is not a useful report. Bucket and count.
• CURATION-MAP is governance. Treat §4 items as the steward's decision queue, not as problems to solve.