blueprints-maintenance

What this skill does

# Maintaining Technical Blueprints

## The Sync Problem

Documentation drifts from implementation when:

- Code changes without doc updates
- New features added without documentation
- Deprecated features remain documented
- Behavior changes aren't reflected

## Verification Process

### Before Making Changes

1. **Find relevant blueprints**:

   ```
   # Search for blueprints related to your system
   Grep("auth", path: "blueprints/", output_mode: "files_with_matches")

   # Read the blueprint to understand current documentation
   Read("blueprints/authentication.md")
   ```

2. **Note what documentation exists**:
   - Overview accurate?
   - API documentation complete?
   - Behavior described correctly?
3. **Plan documentation updates** alongside code changes

### After Making Changes

1. **Re-read the blueprint** to verify accuracy:

   ```
   Read("blueprints/authentication.md")
   ```

2. **Verify each section**:
   - Does Overview still describe the purpose?
   - Are all public APIs documented?
   - Is behavior description accurate?
   - Are file paths still correct?

3. **Update the blueprint**:

   ```
   # Read current content, modify as needed, write back
   Write("blueprints/authentication.md", updated_content_with_frontmatter)
   ```

4. **Remove stale content** - outdated docs mislead

## Types of Updates

### Adding New Features

When adding functionality:

1. Update the Overview if scope expanded
2. Add new API documentation
3. Document new behavior
4. Update Related Systems if new integrations
5. Add to Files section if new files created

### Modifying Existing Features

When changing behavior:

1. Update behavior descriptions
2. Revise API documentation if signatures changed
3. Update examples if usage changed
4. Check related blueprints for impact

### Removing Features

When deprecating or removing:

1. Remove API documentation
2. Remove from behavior section
3. Update Overview if scope reduced
4. Consider keeping a "Removed" or "History" note if the change is significant

### Refactoring

When restructuring without behavior changes:

1. Update Files section with new paths
2. Update Architecture if structure changed
3. Verify examples still work
4. API documentation usually unchanged

## Documentation Debt

### Recognizing Debt

Signs blueprints need attention:

- File paths that don't exist
- Functions that aren't in the codebase
- Behavior that doesn't match reality
- Missing documentation for visible features

### Paying Down Debt

Prioritize by impact:

1. **Critical**: Public APIs with wrong docs
2. **High**: Core systems undocumented
3. **Medium**: Internal systems outdated
4. **Low**: Minor inaccuracies

## Verification Checklist

When reviewing blueprints:

```markdown
## Verification Checklist

- [ ] Overview matches current purpose
- [ ] All public APIs documented
- [ ] API signatures accurate
- [ ] Examples execute correctly
- [ ] Behavior matches implementation
- [ ] File paths exist
- [ ] No removed features documented
- [ ] Related systems links work
- [ ] No duplicate content with other blueprints
```

## Keeping Blueprints Fresh

### During Development

- Treat docs as part of the feature
- Update blueprint in same commit as code
- Review blueprint changes in code review

### Regular Maintenance

- Periodically audit blueprints vs code
- Use `/blueprints` command to regenerate
- Remove orphaned blueprint files

### Tooling Support

The blueprints hooks automatically:

- Remind you to check docs (UserPromptSubmit)
- Verify docs match changes (Stop hook)

## Anti-Patterns

### Don't

- Leave TODO comments in blueprints indefinitely
- Copy implementation details that will change
- Document external libraries (link instead)
- Keep deprecated feature docs "for reference"

### Do

- Delete stale content immediately
- Update atomically with code
- Cross-reference rather than duplicate
- Keep examples minimal but complete