manual_slop/conductor/tracks/gui_2_cleanup_20260513/spec.md

Specification: GUI 2.py Cleanup & Structural Awareness

Overview

This track focuses on studying recent manual cleanups performed on src/gui_2.py to derive best practices for maintaining the Python codebase. It aims to document these extracted conventions, apply them to remaining nitpicks, and significantly enhance the MCP tools' structural awareness of annotations and Python/ImGui conventions.

Functional Requirements

1. Study & Documentation:
   • Study the recent changes made to gui_2.py to identify conventions regarding type hints, state organization, and ImGui rendering patterns.
   • Update conductor/product-guidelines.md with high-level maintenance strategies derived from the study.
   • Update conductor/code_styleguides/python.md with explicit coding conventions discovered (e.g., annotation formatting, class layout).
2. gui_2.py Cleanup (Nitpicks):
   • Apply the formalized conventions to any remaining unorganized sections of gui_2.py (e.g., finishing __init__ refactoring or scattered state).
3. MCP Tools Enhancements:
   • Enhance AST parsing logic (e.g., in Python outline/skeleton extraction) to properly parse and expose type annotations.
   • Modify structural tools to recognize common ImGui/Dear PyGui patterns for better structural awareness and token efficiency.

Non-Functional Requirements

• Ensure changes do not break existing functionality or introduce regressions.
• Maintain the "1-space indentation" rule as strictly defined in the Python code styleguide.
• All refactoring should aim to reduce token consumption when analyzing files with AI.

Acceptance Criteria

• Both conductor/product-guidelines.md and conductor/code_styleguides/python.md are updated with the newly derived insights.
• gui_2.py is successfully refactored according to the formalized conventions.
• MCP tools exhibit improved awareness of annotations and GUI patterns.
• Automated tests pass and manual GUI verification confirms no regressions.

Out of Scope

• Major architectural changes to the underlying AppController or DAG Engine logic.
• Rewriting gui_2.py in a different UI framework.