dcurlewis/.claude/skills/housekeep

Read the latest graph analysis report and interactively fix vault hygiene issues: unresolved wikilinks, dead-end stubs, and orphan notes.

Pre-Requisites

• A graph analysis report must exist in Synced-Data/Graph/ (generated by python3 Scripts/core/graph-analysis.py)

Process

Step 0: Find and Validate Graph Report

1. Glob for Synced-Data/Graph/graph-analysis-*.md. Sort by date suffix (YYYYMMDD) to find the latest.
2. If no report exists, STOP:

   No graph analysis report found. Run this first:
     python3 Scripts/core/graph-analysis.py
   Then re-run /housekeep.
   

3. Extract the date from the filename. Calculate age in days from today.
4. If age > 7 days, warn the user:

   Warning: The latest graph report is from YYYY-MM-DD (N days ago).
   Results may not reflect recent vault changes.
   Consider running `python3 Scripts/core/graph-analysis.py` first.
   Continue anyway? (y/n)
   

   If no, stop. If yes, continue.
5. Read the full report.

Step 1: Parse Report and Present Summary

Parse the Module 1: Graph Health section to extract:

• Summary Statistics table: get counts for unresolved wikilinks, dead-end people stubs, and orphan notes.
• Unresolved Wikilinks (sample) section: extract all [[Link Name]] entries listed.
• Dead-End People Stubs section: extract all listed stub names.
• Orphan Notes section: extract all listed note names and the "...and N more" count if present.

Present a summary dashboard:

Vault Housekeeping (based on YYYY-MM-DD analysis):

| Category                | Total | Shown in report |
|-------------------------|-------|-----------------|
| Unresolved wikilinks    | N     | up to 20        |
| Dead-end people stubs   | N     | up to 30        |
| Orphan notes            | N     | up to 30        |

Processing order: Unresolved wikilinks -> Dead-end stubs -> Orphan notes

If all counts are zero, inform the user and exit: "Vault is clean. No issues to address."

Step 2: Process Unresolved Wikilinks (Interactive)

For each unresolved wikilink extracted from the report:

2a. Pre-verify the link target still does not exist. Check:

• Curated-Context/Entities/People/{link target}.md
• Curated-Context/Entities/Teams/{link target}.md
• Curated-Context/Entities/Vendors/{link target}.md
• Curated-Context/Entities/Projects/{link target}.md

Also check if the link target is an alias of an existing entity. Grep for the link text in frontmatter aliases: fields across Curated-Context/Entities/. Example: [[Ann]] resolves to Ann Sebastian.md via alias.

If the target resolves (file exists or alias matches), mark as "already resolved" and skip silently. Count these for the summary.

2b. Classify the unresolved link. Infer the likely entity type:

• Person (full name): Two or more capitalised words that look like a name. Check the canonical names list in Guidelines/wikilink-guidelines.md for near-matches that suggest a typo.
• Person (alias/first name only): Single first name. Check the canonical names list for a match. If found, the link is already resolvable via alias and should have been caught in 2a. If not found, flag as "unknown person; needs user input."
• Vendor/company: Names that match known company patterns.
• Team/group/org unit: Names containing "Platform", "Team", or matching known team patterns.
• Project/initiative: Multi-word descriptive names.
• Meeting series: Names containing "Weekly", "Sync", "Standup", or time-related words. These typically do not need stubs.
• Unknown: Cannot confidently classify. Present to the user for decision.

2c. Present in batches of approximately 5 items:

Unresolved Wikilinks (batch 1 of N):

1. [[Person Name]] — person (no canonical match)
   -> Suggested: Create person stub
2. [[Misspelled Name]] — possible typo for canonical [[Correct Name]]
   -> Suggested: Fix typo in source files
3. [[Company Name]] — vendor
   -> Suggested: Create vendor stub
4. [[Weekly Sync Meeting]] — meeting series
   -> Suggested: Skip (meeting series don't need stubs)
5. [[FirstName]] — first name only, no canonical match
   -> Suggested: Ask user for full name

For each: (c)reate stub / (s)kip / (f)ix typo / (a)sk user
Or batch: "skip 3,4" / "create all" / "skip all"

Wait for the user's response before proceeding.

2d. Apply fixes based on the user's choice:

• Create stub: Use the stub templates from Guidelines/wikilink-guidelines.md. For people, ask the user for any known metadata (role, team) if not obvious from context. For vendors, projects, and teams, use minimal templates with placeholder content. After creating the stub, add the new entity to the Canonical Names list in Guidelines/wikilink-guidelines.md to prevent future inconsistencies.

• Fix typo: Grep for the misspelled wikilink across Curated-Context/ to find all files containing it. Show the list of affected files and the proposed replacement. Confirm with the user before making the changes.

• Skip: No action. Move to the next item.

• Ask user: Present the context (which files contain this link) and ask the user to identify the entity. Once identified, proceed with stub creation or typo fix.

2e. Truncation note: If the report's total unresolved count exceeds 20, note at the end of this step:

Note: The report samples 20 of N unresolved wikilinks.
Re-run `python3 Scripts/core/graph-analysis.py` after fixes for updated counts.

Step 3: Process Dead-End People Stubs (Interactive)

For each dead-end stub listed in the report:

3a. Pre-verify the stub file still exists at Curated-Context/Entities/People/{Name}.md. If deleted since the report, skip silently.

3b. Read the stub and extract context for the user's decision:

• Role and team (from frontmatter)
• Status (active/departed/unknown)
• Number of timeline entries
• last_updated date
• Whether the person appears in the canonical names list

3c. Present each stub with context:

Dead-end stub: {Name}
  Role: {role or unknown}
  Team: {team or unknown}
  Status: {status}
  Timeline entries: N
  Last updated: YYYY-MM-DD
  In canonical list: yes/no

  Suggested action: {delete if departed + minimal content; keep if active}

  Options: (d)elete / (e)nrich / (k)eep

Wait for the user's response.

3d. Apply fix:

• Delete: Remove the file. If the person is in the canonical names list in Guidelines/wikilink-guidelines.md, remove that entry too.
• Enrich: Ask the user which note should reference this person, or suggest recent notes where the person's name appears in text but without a wikilink. Add a [[wikilink]] to the identified note.
• Keep: No action.

Step 4: Process Orphan Notes (Interactive)

Orphan notes can be high-volume (the report may show 30 of 500+). Handle by group, not individually.

4a. Group by type using filename patterns from the listed orphans:

| Pattern | Type | |---------|------| | *-coach-review-* | Coach reviews | | *-1-on-1-* | 1:1 meeting notes | | *-Interview-* | Interview feedback | | *-Strategy*, *-Summary*, *-Proposal*, *-Decision* | Document summaries | | *-AI-*, *-Platform-* | Technical/platform docs | | Other | Uncategorised |

4b. Present grouped summary:

Orphan Notes (N shown of M total):

| Type               | Count | Oldest         |
|--------------------|-------|----------------|
| Coach reviews      | X     | YYYY-MM-DD     |
| 1:1 meeting notes  | X     | YYYY-MM-DD     |
| Document summaries | X     | YYYY-MM-DD     |
| Technical docs     | X     | YYYY-MM-DD     |
| Uncategorised      | X     | YYYY-MM-DD     |

Per group: (r)eview individually / (s)kip group / (e)nrich group

Wait for the user's response per group.

4c. If review individually: For each note in the group, show the filename and ask: (d)elete / (l)ink (add wikilinks to content) / (k)eep.

4d. If enrich group: For each note in the group:

1. Read the note content.
2. Identify people, teams, vendors, and projects mentioned in the text that match canonical names.
3. Add [[wikilinks]] to first mentions per section, following Guidelines/wikilink-guidelines.md rules.
4. Do not modify headings, quotes, or metadata blocks.

4e. Truncation note: If the total orphan count exceeds the shown count:

Note: M orphan notes exist; the report shows N.
The remaining orphans can be addressed by running /housekeep again after
re-generating the graph analysis report, or via retroactive wikilink enrichment.

Step 5: Summary

Display a concise summary of all actions taken:

Housekeeping complete:

Unresolved wikilinks:
  - N already resolved (since report)
  - N stubs created
  - N typos fixed
  - N skipped
  - N asked/deferred

Dead-end stubs:
  - N deleted
  - N enriched
  - N kept

Orphan notes:
  - N enriched with wikilinks
  - N deleted
  - N kept/skipped

Files created:  [list if any]
Files deleted:  [list if any]
Files modified: [list if any]

Recommendation: Run `python3 Scripts/core/graph-analysis.py` to regenerate
the report with updated counts.

Graceful Degradation

| Missing piece | Behaviour | |---|---| | No graph report exists | STOP with instructions to run python3 Scripts/core/graph-analysis.py | | Report is > 7 days old | Warn interactively; proceed if user confirms | | Report shows truncated lists | Note truncation; recommend re-running analysis after fixes | | Stub file referenced in report no longer exists | Skip silently; count as "already resolved" in summary | | Unresolved link was resolved since report | Skip silently; count as "already resolved" in summary | | Wikilink target is an alias | Detect via frontmatter grep; skip silently | | Cannot determine entity type | Present as "unknown" and ask the user to classify | | No items in a category | Skip that category's step entirely |