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

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")

Note what documentation exists:

• Overview accurate?

• API documentation complete?

• Behavior described correctly?

Plan documentation updates alongside code changes

After Making Changes

Re-read the blueprint to verify accuracy:

Read("blueprints/authentication.md")

Verify each section:

• Does Overview still describe the purpose?

• Are all public APIs documented?

• Is behavior description accurate?

• Are file paths still correct?

Update the blueprint:

Read current content, modify as needed, write back

Write("blueprints/authentication.md", updated_content_with_frontmatter)

Remove stale content - outdated docs mislead

Types of Updates

Adding New Features

When adding functionality:

• Update the Overview if scope expanded

• Add new API documentation

• Document new behavior

• Update Related Systems if new integrations

• Add to Files section if new files created

Modifying Existing Features

When changing behavior:

• Update behavior descriptions

• Revise API documentation if signatures changed

• Update examples if usage changed

• Check related blueprints for impact

Removing Features

When deprecating or removing:

• Remove API documentation

• Remove from behavior section

• Update Overview if scope reduced

• Consider keeping a "Removed" or "History" note if the change is significant

Refactoring

When restructuring without behavior changes:

• Update Files section with new paths

• Update Architecture if structure changed

• Verify examples still work

• 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:

• Critical: Public APIs with wrong docs

• High: Core systems undocumented

• Medium: Internal systems outdated

• Low: Minor inaccuracies

Verification Checklist

When reviewing blueprints:

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