documentation-index-maintenance

name	documentation-index-maintenance
description	Maintain and fix inconsistencies in documentation indexes, tables of contents, and structured markdown files
type	skill
tags	["documentation","maintenance","productivity","patch"]

Documentation Index Maintenance Skill

Maintain and fix inconsistencies in documentation indexes, tables of contents, and structured markdown files. Includes locating files, reading content, making targeted patches, and verifying changes.

When to Use

• Fixing broken links in documentation indexes
• Correcting category/classification errors in skill/table listings
• Updating file references when files are renamed or moved
• Maintaining consistency in structured documentation files
• Any task involving precise edits to markdown tables or lists

Steps

1. Locate the Target File

Use search strategies to find the documentation file:

# Search by filename (exact or partial)
search_files(pattern="index.md", target="files", path="~/Documents/Obsidian")

# Search by content (when filename unknown)
search_files(pattern="Skills Hermes Index", target="content", path="~/Documents/Obsidian")

# Search in specific directories
search_files(pattern="*.md", target="files", path="~/Documents/Obsidian/Notes/Skills Hermes")

2. Read and Analyze Current Content

Examine the file to understand its structure and identify issues:

read_file(path="/path/to/file.md")

Look for:

• Inconsistent categories or classifications
• Broken or incorrect links
• Missing entries
• Formatting issues in tables or lists

3. Plan Targeted Fixes

For each inconsistency identified, prepare:

• Exact old string to replace (include sufficient context for uniqueness)
• Correct new string
• Verification method

4. Apply Patches Using the patch Tool

Make precise, context-aware replacements:

patch(
    path="/path/to/file.md",
    mode="replace",
    old_string="exact context including the problematic text",
    new_string="same context with corrections",
    replace_all=false  # Usually false for precision
)

5. Verify Changes

Always verify patches were applied correctly:

read_file(path="/path/to/file.md")  # Review the changes
# Or for specific verification:
search_files(pattern="corrected text", target="content", path="/path/to/file.md")

Best Practices

For Precision

• Include sufficient surrounding context in old_string to ensure uniqueness
• Typically 20-50 characters before and after the target text
• Include line breaks or markdown syntax when relevant
• Test uniqueness by checking if the pattern appears only once

Common Pitfalls to Avoid

• Don't use replace_all=true unless you're certain
• Don't make patches that are too broad (might match unintended text)
• Always verify after each patch
• Keep backups of important documentation before major changes

Workflow Tips

• Work on one inconsistency at a time
• Verify each fix before moving to the next
• Group similar fixes together when they're in the same file section
• Document what you fixed for future reference

Example: Fixing a Skill Index Entry

Problem: google-calendar-wfo-integration shows category "N/A" but should be "productivity"

Old String (with context):

|| google-calendar-wfo-integration | N/A          | [google-calendar-wfo-integration.md](google-calendar-wfo-integration.md) |

New String:

|| google-calendar-wfo-integration | productivity | [google-calendar-wfo-integration.md](google-calendar-wfo-integration.md) |

Patch Command:

patch(
    path="~/Documents/Obsidian/Notes/Skills Hermes/index.md",
    old_string="|| google-calendar-wfo-integration | N/A          | [google-calendar-wfo-integration.md](google-calendar-wfo-integration.md) |",
    new_string="|| google-calendar-wfo-integration | productivity | [google-calendar-wfo-integration.md](google-calendar-wfo-integration.md) |"
)

Verification Checklist

• File located correctly
• Current content read and understood
• All inconsistencies identified
• Each fix planned with unique context
• Each patch applied successfully
• All changes verified
• No unintended modifications made

Related Skills

• skill-documentation: For creating skill documentation from scratch
• obsidian: For general Obsidian vault operations
• patch: For making precise file edits (this skill builds on it)