Skip to main content

Epic 6, Story 7, Task 15: Cursor IDE Performance Considerations Awareness

Status: ✅ COMPLETE
Priority: MEDIUM
Last updated: 2025-12-21 (v0.6.7.15+1 – Implementation complete: Awareness documentation created and framework guidance updated, migrated from v0.6.6.15+1)
Started: 2025-12-21
Completed: 2025-12-21
Version: v0.6.7.15+1

Feature Request: FR-028
Code: E6S07T15

Task ID​

Format: E\{epic\}:S\{story\}:T\{task\} Value: E6:S07:T15

Scope​

Create awareness documentation and update framework guidance for Cursor IDE performance considerations based on real-world investigation of IDE crashes in large projects. Ensure adopting projects are aware of potential performance issues and best practices to prevent IDE crashes.

Problem Statement:

  • Large projects can experience Cursor IDE crashes during bulk operations
  • Investigation in Confidentia project identified root causes (pre-commit hooks, large file counts, bulk operations, file watching overhead)
  • ai-dev-kit currently has 1,021 markdown files (growing), 266 changelog archive files, 181 Kanban files
  • Framework documentation shows pass_filenames: false as example (problematic pattern)
  • No awareness documentation exists for IDE performance considerations

Solution:

  1. Create awareness document: docs/architecture/standards-and-adrs/cursor-ide-performance-considerations.md
  2. Update framework documentation to use pass_filenames: true examples
  3. Add performance notes and best practices
  4. Reference external investigation (Confidentia project)

Input​

  • Feature Request: FR-028-cursor-ide-performance-considerations-awareness.md

    • Problem statement and proposed solution
    • Acceptance criteria

  • External Investigation: Confidentia project (Epic 20, Story 5, Task 16)

    • Bug Report: KB/PM_and_Portfolio/kanban/Epic 20/Story-5-BR-Cursor-IDE-Crashes.md
    • Investigation Report: KB/Documentation/Developer_Docs/cursor-crash-investigation.md
    • Article: KB/Documentation/Developer_Docs/cursor-crash-investigation-article.md

  • Framework Documentation: packages/frameworks/numbering & versioning/IMPLEMENTATION_GUIDE.md

  • Current File Counts: ai-dev-kit statistics (1,021 markdown files, 266 changelog archive files, 181 Kanban files)

Deliverable​

Awareness Documentation and Framework Updates:

  1. Awareness Document Created:

    • File: docs/architecture/standards-and-adrs/cursor-ide-performance-considerations.md
    • Content: Root causes, best practices, monitoring, framework guidance, action items
    • References external investigation appropriately

  2. Framework Documentation Updated:

    • File: packages/frameworks/numbering & versioning/IMPLEMENTATION_GUIDE.md
    • Change: Pre-commit hook examples use pass_filenames: true instead of pass_filenames: false
    • Add: Performance notes explaining the recommendation
    • Add: Best practices section

  3. Documentation Structure:

    • Follows existing ADR/documentation patterns
    • Links to related framework documentation
    • Provides actionable guidance for adopting projects

Approach​

Phase 1: Create Awareness Document​

  1. Create Document:

    • File: docs/architecture/standards-and-adrs/cursor-ide-performance-considerations.md
    • Structure: Overview, Problem Statement, Root Causes, Best Practices, Monitoring, Framework Guidance, Action Items

  2. Content Sections:

    • Overview: Problem statement and impact
    • Root Causes: Pre-commit hooks, large file counts, bulk operations, file watching overhead
    • Best Practices: Pre-commit hooks, file operations, IDE configuration
    • Monitoring: Warning signs, measurement commands, thresholds
    • Framework Guidance: Recommendations for adopting projects
    • Action Items: For ai-dev-kit and adopting projects

  3. Reference External Investigation:

    • Link to Confidentia project investigation
    • Cite bug report, investigation report, and article
    • Acknowledge source of findings

Phase 2: Update Framework Documentation​

  1. Update Pre-commit Hook Examples:

    • Change from pass_filenames: false to pass_filenames: true
    • Add files: pattern for changelog validation hook
    • Update script usage examples

  2. Add Performance Notes:

    • Explain why pass_filenames: true is recommended
    • Link to awareness document
    • Warn about performance implications of pass_filenames: false

  3. Add Best Practices Section:

    • Pre-commit hook configuration
    • File operation batching
    • .cursorignore usage
    • Monitoring recommendations

Acceptance Criteria​

  • Awareness document created: docs/architecture/standards-and-adrs/cursor-ide-performance-considerations.md
  • Document includes all required sections (Overview, Root Causes, Best Practices, Monitoring, Framework Guidance, Action Items)
  • External investigation referenced (Confidentia project)
  • Framework implementation guide updated with pass_filenames: true examples
  • Performance notes added explaining recommendations
  • Best practices documented (pre-commit hooks, file operations, IDE configuration)
  • Monitoring guidelines included
  • Action items documented for ai-dev-kit and adopting projects
  • Documentation follows existing ADR/documentation patterns
  • Links to related framework documentation

Dependencies​

Blocks:

  • None

Blocked By:

  • None

Coordinates With:

  • External Investigation: Confidentia project (Epic 20, Story 5, Task 16)
  • Framework Documentation: Numbering & Versioning Framework implementation guide

Feature Request:

  • FR-028: Cursor IDE Performance Considerations Awareness (source of this task)

External Investigation:

  • Confidentia Project: Epic 20, Story 5, Task 16
    • Bug Report: KB/PM_and_Portfolio/kanban/Epic 20/Story-5-BR-Cursor-IDE-Crashes.md
    • Investigation Report: KB/Documentation/Developer_Docs/cursor-crash-investigation.md
    • Article: KB/Documentation/Developer_Docs/cursor-crash-investigation-article.md

Related Stories:

  • E6:S07: ADK Implementation Analysis and Package Management (parent story, migrated from S06 to S07)

Related Epics:

  • Epic 6: Framework Management and Maintenance

Notes​

Documentation Style:

  • Follow existing ADR/documentation structure
  • Maintain consistency with other standards documents
  • Use clear, actionable language
  • Provide concrete examples

Framework Updates:

  • Update examples to promote best practices
  • Add performance notes without breaking existing documentation flow
  • Maintain backward compatibility where possible

Priority:

  • MEDIUM priority (preventive documentation, not blocking)
  • Based on real-world investigation (proven need)
  • Helps adopting projects avoid performance issues

Last Updated: 2025-12-21 (v0.6.7.15+1 – Implementation complete: Awareness documentation created and framework guidance updated, migrated from v0.6.6.15+1)
Version: v0.6.7.15+1
Status: ✅ COMPLETE