Tag Management Skill

Purpose: Analyze, refactor, and maintain tags across the vault according to the official taxonomy.

Taxonomy Reference: [[.claude/rules/tag-taxonomy.md]]

Commands

/tag-analyze [scope]

Analyze tag quality and compliance.

Scopes:

• •/tag-analyze - Current note (if applicable)
• •/tag-analyze vault - Full vault analysis
• •/tag-analyze <path> - Specific file or folder

Analysis Includes:

1. •Tag coverage (has tags vs no tags)
2. •Hierarchical compliance (proper prefixes)
3. •Case violations (uppercase, mixed case)
4. •Inline prefix violations (# in frontmatter)
5. •Template variable contamination
6. •Flat tag orphans (no hierarchy)
7. •Minimum tag requirements by note type
8. •Tag recommendations

Output:

• •Summary of violations
• •Specific issues found
• •Suggested fixes

/tag-refactor [scope]

Refactor tags to follow official taxonomy.

Scopes:

• •/tag-refactor - Current note
• •/tag-refactor vault - Full vault refactor
• •/tag-refactor <path> - Specific file or folder
• •/tag-refactor --dry-run - Preview changes without applying

Refactoring Rules:

1. •

   Case Normalization

   • •ADR → type/adr
   • •MROSystem → technology/mroPlatform
   • •AWS → technology/aws
   • •All tags to lowercase
2. •

   Inline Prefix Removal

   • •#activity/architecture → activity/architecture
   • •#technology/aws → technology/aws
3. •

   Flat to Hierarchical

   • •mroSystem → technology/mroPlatform
   • •aws → technology/aws
   • •dataPlatform → project/dataPlatform
   • •architecture → activity/architecture
   • •integration → domain/integration or activity/integration (context-dependent)
4. •

   Template Variable Removal

   • •Delete: {{3-5 relevant tags}}, {{project|lower}}, etc.
5. •

   Capitalized Prefixes

   • •Project/ModernizationProject → project/modernization
   • •Technology/AWS → technology/aws

Safety:

• •Always backup before vault-wide refactoring
• •Preview changes with --dry-run first
• •Commit changes to git before refactoring

/tag-suggest <note>

Suggest appropriate tags for a note based on content analysis.

Process:

1. •Read note frontmatter and content
2. •Analyze note type (type: field)
3. •Extract key terms and context
4. •Suggest tags from approved taxonomy

Example:

/tag-suggest "ADR - AIIncidentProcessor - Bedrock.md"

Output:

# Current tags:
tags: [ADR, activity/architecture, AWS, Bedrock]

# Suggested tags (normalized):
tags: [
  type/adr,
  activity/architecture,
  technology/aws,
  technology/bedrock,
  project/aiProcessor,
  domain/cloud,
  domain/security
]

# Changes:
- Remove: ADR (flat) → Add: type/adr
- Normalize: AWS → technology/aws
- Normalize: Bedrock → technology/bedrock
- Add missing: project/aiProcessor, domain/cloud, domain/security

/tag-find-violations [type]

Find specific tag violations across the vault.

Types:

• •/tag-find-violations case - Case violations (uppercase, mixed case)
• •/tag-find-violations inline - Inline # prefix in frontmatter
• •/tag-find-violations flat - Orphan flat tags (no hierarchy)
• •/tag-find-violations template - Template variable contamination
• •/tag-find-violations missing - Notes missing required tags
• •/tag-find-violations all - All violations (default)

Output:

• •List of files with violations
• •Specific violations per file
• •Count summary

/tag-migrate <old> <new>

Batch rename a tag across the entire vault.

Examples:

/tag-migrate "ADR" "type/adr"
/tag-migrate "AWS" "technology/aws"
/tag-migrate "project/modernization" "project/modernization-legacy"

Process:

1. •Find all notes with <old> tag
2. •Replace with <new> tag
3. •Update frontmatter YAML
4. •Report changes made

Safety:

• •Shows preview before applying
• •Requires confirmation for vault-wide changes

Implementation Guide

Tag Refactoring Process

When implementing /tag-refactor:

1. •

   Read note frontmatter

   python

   import re, yaml
   
   with open(file_path) as f:
       content = f.read()
   
   # Extract frontmatter
   match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
   frontmatter = yaml.safe_load(match.group(1))
   tags = frontmatter.get('tags', [])
   

2. •

   Apply refactoring rules

   python

   refactored_tags = []
   
   for tag in tags:
       # Remove inline prefix
       tag = tag.lstrip('#')
   
       # Apply migrations
       tag = apply_migrations(tag, note_type, note_content)
   
       # Normalize case
       tag = tag.lower()
   
       # Skip template variables
       if '{{' in tag:
           continue
   
       refactored_tags.append(tag)
   

3. •

   Contextual flat tag resolution

   python

   def apply_migrations(tag, note_type, content):
       # Simple mappings
       FLAT_TO_HIERARCHICAL = {
           'adr': 'type/adr',
           'mroSystem': 'technology/mroPlatform',
           'aws': 'technology/aws',
           'ai': 'technology/ai',
           'dataPlatform': 'project/dataPlatform',
           'modernization': 'project/modernization',
           'myProject': 'project/myProject',
           'moc': 'moc',  # Approved special tag
           'daily': 'daily',  # Approved special tag
       }
   
       # Context-dependent
       if tag == 'architecture':
           # Check if it's an activity or domain
           if 'decision' in content.lower() or note_type == 'Adr':
               return 'activity/architecture'
           else:
               return 'domain/engineering'
   
       if tag == 'integration':
           if 'integration pattern' in content.lower():
               return 'activity/integration'
           else:
               return 'domain/integration'
   
       # Direct mapping
       if tag in FLAT_TO_HIERARCHICAL:
           return FLAT_TO_HIERARCHICAL[tag]
   
       # Already hierarchical - normalize case only
       return tag
   

4. •

   Update frontmatter

   python

   frontmatter['tags'] = refactored_tags
   
   # Rebuild YAML
   new_frontmatter = yaml.dump(frontmatter, sort_keys=False)
   
   # Replace in file
   new_content = re.sub(
       r'^---\n.*?\n---',
       f'---\n{new_frontmatter}---',
       content,
       count=1,
       flags=re.DOTALL
   )
   
   with open(file_path, 'w') as f:
       f.write(new_content)
   

Tag Migration Reference

Common Flat Tag Migrations

Capitalized Hierarchy Migrations

Inline Prefix Removal

Usage Examples

Example 1: Analyze Current Note

$ /tag-analyze

Analyzing: ADR - AIIncidentProcessor - Bedrock.md

Current tags: [ADR, activity/architecture, AWS, Bedrock, aiProcessor]

Issues Found:
✗ Flat tag: ADR (should be type/adr)
✗ Case violation: AWS (should be technology/aws)
✗ Flat tag: Bedrock (should be technology/bedrock)
✗ Flat tag: aiProcessor (should be project/aiProcessor)
✗ Missing minimum tags: Only 5 tags, ADRs need 4-7 with required hierarchies

Missing Required Hierarchies:
✗ No domain/ tag (required for ADRs)

Suggestions:
+ Add: type/adr (artifact type)
+ Add: technology/aws (platform)
+ Add: technology/bedrock (AI service)
+ Add: project/aiProcessor (project context)
+ Add: domain/cloud (business area)
+ Add: domain/security (security considerations)

Recommended tags:
tags: [type/adr, activity/architecture, technology/aws, technology/bedrock, project/aiProcessor, domain/cloud, domain/security]

Example 2: Refactor Vault (Dry Run)

$ /tag-refactor vault --dry-run

Vault Tag Refactoring Preview
==============================

Analyzing 2,535 markdown files...

Summary:
- 732 files with tags to refactor
- 1,148 files with no tags (skipped)
- 655 files with empty tags [] (skipped)

Changes Preview (first 10):

1. ADR - AIIncidentProcessor - Bedrock.md
   - Remove: ADR → Add: type/adr
   - Normalize: AWS → technology/aws
   - Normalize: Bedrock → technology/bedrock
   - Normalize: aiProcessor → project/aiProcessor

2. Project - MyDataIntegration.md
   - Remove: Project → Add: project/myProject
   - Normalize: SAP → technology/sap
   - Add recommended: domain/data, domain/integration

3. System - DataPlatform.md
   - Remove inline: #activity/architecture → activity/architecture
   - Normalize: DataPlatform → type/system
   - Add missing: criticality/critical

...

Total Changes:
- 124 case normalizations
- 67 flat to hierarchical conversions
- 10 inline prefix removals
- 11 template variable deletions
- 203 recommended tags to add

Run without --dry-run to apply changes.
Recommend: git commit current state first.

Example 3: Find Specific Violations

$ /tag-find-violations case

Finding case violations across vault...

Found 47 files with case violations:

1. ADR - SAP to AWS Connectivity.md
   - ADR (should be lowercase in hierarchy)
   - AWS (should be lowercase in hierarchy)

2. Project - ModernizationProject.md
   - MROPlatform (should be lowercase)
   - SAP (should be lowercase)

3. Meeting - 2026-01-10 ECP Core.md
   - ECP (should be lowercase or hierarchical)

...

Summary:
- 24 files with uppercase flat tags
- 18 files with mixed case in hierarchies
- 5 files with capitalized prefixes (Project/, Technology/)

Run /tag-refactor to fix these violations.

Example 4: Migrate Specific Tag

$ /tag-migrate "ADR" "type/adr"

Migrating tag: ADR → type/adr

Found 41 files with tag "ADR":
1. ADR - API Gateway Selection.md
2. ADR - AIIncidentProcessor - AI Services.md
3. ADR - AIIncidentProcessor - Bedrock.md
...

Preview changes? [y/N]: y

Changes to apply:
- Replace "ADR" with "type/adr" in 41 files
- Preserve all other tags
- Update frontmatter YAML

Apply changes? [y/N]: y

✓ Updated 41 files successfully
✓ No errors

Summary:
- 41 files updated
- 0 files skipped
- 0 errors

Best Practices

1. •Always run --dry-run first - Preview changes before applying
2. •Commit to git before refactoring - Easy rollback if needed
3. •Refactor incrementally - Start with specific violations, then full vault
4. •Review suggestions - AI suggestions may need manual adjustment
5. •Use /tag-suggest liberally - Get recommendations for new notes
6. •Run quarterly audits - Use /tag-analyze vault to monitor quality

Integration with Other Skills

This skill works well with:

• •/quality-report - Includes tag analysis
• •/vault-maintenance - Includes tag health checks
• •/adr - Suggests tags when creating ADRs
• •/project-status - Analyzes project tags

References

• •[[.claude/rules/tag-taxonomy.md]] - Official taxonomy (authoritative)
• •[[.claude/vault-conventions.md]] - Tag syntax and conventions
• •[[.claude/rules/quality-patterns.md]] - Quality patterns and tag guidance

Sources:

• •Knowledge Base Taxonomy: 10 Proven Design Principles
• •Taxonomy 101: Definition and Best Practices - Nielsen Norman Group
• •Personal Knowledge Management at Scale