By name: jd-jdex-audit description: > Audit a Johnny.Decimal system by comparing the JDex against the actual folder structure, flagging mismatches, orphaned entries, and undocumented folders. Use this skill when the user wants to verify their JD system, check for inconsistencies, sync their JDex with the filesystem, or says things like "audit my JDex," "check my system," "sync JDex," "verify my JD system," "is my JDex up to date," or "find orphaned folders."
Johnny.Decimal JDex Audit
This skill compares a system's JDex (the authoritative index) against the actual folder structure on disk, identifying mismatches and suggesting fixes.
1. Locate the System
1.1 Find the JD Root
Check common locations:
~/Library/Mobile Documents/com~apple~CloudDocs/JD/(iCloud Drive)~/Documents/JD/~/JD/
If the user specifies a system code (e.g., "audit my P10 system"), target that specific system. Otherwise, list all available systems and ask which to audit.
1.2 Load the JDex
Read the JDex file at:
SYS/00-09 */00 */00.00 *JDex*
Parse it into a structured list of areas, categories, and IDs. Each entry should capture:
- The AC.ID (or SYS.AC.ID) address
- The description/name
- Any +SUB entries
1.3 Snapshot the Filesystem
List all folders to depth 3 under the system root. Parse folder names to extract AC.ID addresses, area ranges, and category numbers.
2. Compare JDex vs. Filesystem
Run three checks:
2.1 Orphaned JDex Entries
JDex entries that have no corresponding folder on disk.
These indicate either:
- A folder was deleted without updating the JDex
- A planned ID that was never created
- A typo in the JDex entry
2.2 Undocumented Folders
Folders on disk that have no corresponding JDex entry.
These indicate either:
- A folder was created without updating the JDex
- The JDex fell out of sync during manual organization
- A folder created by another tool or process
2.3 Name Mismatches
JDex entries whose description doesn't match the folder name, or folders
whose name doesn't follow the expected AC.ID Description format.
3. Check +SUB Indexes
For categories that use +SUB extensions:
3.1 Locate Index Files
+SUB categories typically have an index file (e.g., 51.01 Open-source project index.md). Find these by looking for files matching *.md at the category
or ID level that contain +SUB listings.
3.2 Compare Index vs. Folders
- List all
+NNNNor+CODEfolders within the ID - Compare against the index file entries
- Flag missing or extra entries
4. Report Findings
Present a clear audit report to the user:
Report Format
## JDex Audit: [System name]
**Audit date:** YYYY-MM-DD
**JDex location:** [path]
**System root:** [path]
### Summary
| Check | Count |
|-------|-------|
| JDex entries | N |
| Filesystem folders | N |
| Orphaned JDex entries | N |
| Undocumented folders | N |
| Name mismatches | N |
| +SUB index issues | N |
### Orphaned JDex Entries (in JDex but no folder)
| AC.ID | Description | Suggested Action |
|-------|-------------|-----------------|
| 11.05 | Home improvement | Create folder or remove from JDex |
### Undocumented Folders (folder exists but not in JDex)
| Folder | Path | Suggested Action |
|--------|------|-----------------|
| 11.08 Garage storage | 10-19/11/11.08 | Add to JDex |
### Name Mismatches
| AC.ID | JDex says | Folder says | Suggested Action |
|-------|-----------|-------------|-----------------|
| 11.03 | Home insurance | Homeowners insurance | Reconcile names |
### +SUB Index Issues
| Category | Issue | Details |
|----------|-------|---------|
| 51.01 | Missing from index | +0004 folder exists, not in index |
5. Offer Fixes
After presenting the report, offer to fix issues:
Safe Fixes (do automatically with confirmation)
- Add undocumented folders to JDex: Append new entries matching the folder names.
- Update +SUB index files: Add missing entries to index files.
Requires User Decision
- Orphaned JDex entries: Ask whether to create the missing folder or remove the JDex entry.
- Name mismatches: Ask which name is correct (JDex or folder) and update the other.
Never Do Automatically
- Delete folders: Even if they appear orphaned, never delete without explicit user confirmation.
- Rename folders: Name changes can break references. Always confirm first.
- Create new areas or categories: These are structural decisions.
6. Regenerate JDex (Optional)
If the user requests it, offer to regenerate the JDex entirely from the folder structure:
- Walk the filesystem and build a complete list of areas, categories, and IDs.
- Preserve any JDex-only metadata (cross-system references, notes, +SUB descriptions) from the existing JDex.
- Write the new JDex, merging filesystem reality with JDex metadata.
- Present the result for user approval before overwriting.
Warning: Regeneration loses any JDex entries that don't have corresponding folders. Always confirm before proceeding.
7. Multi-System Audit
When auditing multiple systems:
- Audit each system independently.
- Present per-system reports.
- Optionally check cross-system references: if P10.34.01 is referenced by F50.32.01, verify that both the source and the reference exist.
- Provide a combined summary at the end.