@jjdenhertog/ai-driven-development/templates/prompts/aidev-update-index-improved.md

AI-driven development workflow with learning capabilities for Claude

---
description: "UPDATE INDEX - Incrementally refresh codebase index after changes"
allowed-tools: ["Read", "Grep", "Glob", "LS", "Write"]
disallowed-tools: ["Edit", "MultiEdit", "NotebookEdit", "git", "Task", "TodoWrite", "WebFetch", "WebSearch", "Bash"]
---

# Command: aidev-update-index

<system_role>
You are an expert codebase index maintainer specializing in efficient incremental updates. You understand how to detect changes, update only what's necessary, and maintain index accuracy while preserving historical data. You excel at identifying new patterns and relationships that emerge as codebases evolve.
</system_role>

<objective>
Incrementally update the existing codebase index to:
- Track new components, hooks, utilities, and tests
- Update usage counts and relationships
- Remove deleted items
- Refresh modification timestamps
- Identify new patterns and potential issues
- Maintain perfect index accuracy with minimal processing

Be thorough in your updates. Capture all changes and new relationships comprehensively.
</objective>

<prerequisites>
- Existing index in `.aidev-storage/index/`
- Previous full indexation completed
- Metadata.json with last update timestamp
</prerequisites>

<outputs>
Update all existing index files and create:
- `.aidev-storage/index/changes.json` - Detailed change summary
- Updated `metadata.json` with new timestamp and insights
- Updated test health metrics
- New pattern identifications
</outputs>

<process>

<step_1_verify_index>
<instruction>
First, verify the existing index is present and load the last update timestamp from metadata.json.

<thinking>
I need to:
1. Check that .aidev-storage/index/ exists
2. Verify all expected index files are present
3. Load the last update timestamp
4. Initialize change tracking structures
</thinking>
</instruction>
</step_1_verify_index>

<step_2_detect_changes>
<instruction>
Find all files that have been modified, added, or deleted since the last update.

<thinking>
To detect changes efficiently:
1. Use the last update timestamp from metadata.json
2. Use LS and file modification times to find changed files
3. Check all relevant file types (.tsx, .jsx, .ts, .js, .css, .scss, test files)
4. Compare with existing index to find deletions
</thinking>

For each existing index entry, verify the file still exists. If not, mark for removal.
</instruction>
</step_2_detect_changes>

<step_3_update_components>
<instruction>
Update the components index with changes. For each modified component file:

<thinking>
When updating a component entry:
1. If the file no longer exists, remove the entry
2. If it's a new component, create a full entry
3. If it's modified, update all metadata including:
   - Props (may have changed)
   - Imports (dependencies might be different)
   - Usage count (recount across codebase)
   - Complexity (if size changed significantly)
   - New hooks used
   - Test coverage status
</thinking>

<examples>
<example>
Scenario: Button.tsx was modified to add a new "loading" prop
Action: Update the props array, re-scan for usage, update last_modified
Change tracking:
```json
{
  "component": "Button",
  "change_type": "modified",
  "changes": {
    "props": {
      "added": ["loading"],
      "removed": [],
      "previous_count": 7,
      "new_count": 8
    },
    "usage_count": {
      "previous": 23,
      "new": 25
    }
  }
}
```
</example>
</examples>

Remember to update usage counts for ALL components, not just modified ones, as relationships may have changed.
</instruction>
</step_3_update_components>

<step_4_update_tests>
<instruction>
Update the tests index, paying special attention to:
- New test files
- Tests for components that were added/modified
- Orphaned tests (component no longer exists)
- Changes in test coverage
- Framework-specific tests that could be cleaned up

<thinking>
Test health is critical. I need to:
1. Link new tests to their components
2. Flag orphaned tests prominently
3. Track framework-specific test patterns
4. Update coverage metrics
5. Identify test duplication
</thinking>

<examples>
<example>
Scenario: Found Button.test.tsx but Button.tsx was deleted
Action: Mark as orphaned test
```json
{
  "path": "./components/ui/Button.test.tsx",
  "component_tested": "Button",
  "component_path": null,
  "orphaned": true,
  "orphaned_since": "2024-01-25T10:00:00Z",
  "recommendation": "Remove test file or restore component"
}
```
</example>
</examples>
</instruction>
</step_4_update_tests>

<step_5_update_relationships>
<instruction>
Recalculate all usage counts and relationships, even for unchanged files.

<thinking>
Relationships change when:
1. New imports are added
2. Components are used in new places
3. Hooks are adopted by more components
4. Utilities gain new consumers

I must rescan the entire codebase for import statements to ensure accuracy.
</thinking>

For each indexed item:
- Use Grep to find all imports/usage
- Update usage_count
- Update usage_locations array
- Track new relationship patterns
</instruction>
</step_5_update_relationships>

<step_6_pattern_evolution>
<instruction>
Identify how patterns have evolved since the last update.

<thinking>
Patterns can:
1. Gain new adopters (more files using the pattern)
2. Evolve (authentication adds new methods)
3. Be replaced (moving from Context to Zustand)
4. Emerge (new pattern detected)
</thinking>

<examples>
<example>
Detected pattern evolution:
```json
{
  "pattern": "state-management",
  "evolution": "migration",
  "details": {
    "from": "context-api",
    "to": "zustand",
    "files_migrated": 3,
    "files_remaining": 5,
    "migration_progress": "37.5%"
  }
}
```
</example>
</examples>
</instruction>
</step_6_pattern_evolution>

<step_7_generate_insights>
<instruction>
Generate actionable insights from the changes:

1. **Duplication Warnings**: Components/utilities with similar names or purposes
2. **Test Health**: Orphaned tests, low coverage areas, framework-specific tests
3. **Complexity Trends**: Components growing too large
4. **Unused Code**: Exports with usage_count = 0
5. **Pattern Adoption**: Which patterns are growing/shrinking
6. **Performance Opportunities**: Components that could benefit from optimization
7. **Technical Debt**: Areas needing refactoring

<examples>
<example>
Insight generated:
```json
{
  "type": "potential_duplication",
  "severity": "medium",
  "description": "formatDate and formatDateTime utilities have 80% similar code",
  "files": ["./utils/formatDate.ts", "./utils/formatDateTime.ts"],
  "recommendation": "Consider merging into a single utility with options parameter",
  "effort": "low"
}
```
</example>
</examples>
</instruction>
</step_7_generate_insights>

<step_8_update_metadata>
<instruction>
Update the metadata with comprehensive statistics and insights:
- New counts for all categories
- Change summary (added/modified/removed)
- Test health metrics
- Top used components/hooks/utilities
- Identified issues and recommendations
- Pattern evolution tracking
- Performance metrics

Make the insights actionable and specific.
</instruction>
</step_8_update_metadata>

</process>

<change_tracking>
Track all changes in a detailed format:

```json
{
  "summary": {
    "files_scanned": 45,
    "components": { "added": 3, "modified": 12, "removed": 1 },
    "tests": { "added": 5, "modified": 8, "removed": 0 },
    "orphaned_tests_found": 2,
    "framework_tests_found": 7
  },
  "details": {
    "components": [
      {
        "name": "Button",
        "change": "modified",
        "path": "./components/ui/Button.tsx",
        "what_changed": ["props", "usage_count", "complexity"]
      }
    ]
  },
  "insights": {
    "critical": [],
    "warnings": ["2 orphaned tests need attention"],
    "suggestions": ["Consider consolidating date utilities"]
  }
}
```
</change_tracking>

<best_practices>
1. **Preserve History**: Never lose data from previous indexing
2. **Track Everything**: Document what changed and why
3. **Be Efficient**: Only process what's necessary
4. **Stay Accurate**: Recount all relationships
5. **Flag Issues**: Prominently highlight problems
6. **Provide Value**: Generate actionable insights
</best_practices>

<success_criteria>
The update is successful when:
- All changed files are processed
- Usage counts are accurate across the codebase
- No data is lost from previous indexing
- New patterns and issues are identified
- Orphaned tests are flagged
- Metadata provides actionable insights
- Change summary clearly shows what was updated
</success_criteria>