diff --git a/src/mir/builder/control_flow/debug.rs b/src/mir/builder/control_flow/debug.rs
index 43c48e7d..b3d1ada9 100644
--- a/src/mir/builder/control_flow/debug.rs
+++ b/src/mir/builder/control_flow/debug.rs
@@ -1,4 +1,11 @@
-//! Debug utilities for control flow tracing
+//! Debug utilities for control flow tracing.
+//!
+//! This module provides diagnostic tools for tracing and debugging
+//! control flow behavior during MIR construction.
+//!
+//! # Environment Variables
+//!
+//! - `NYASH_TRACE_VARMAP=1` - Enable variable map tracing
 
 use super::super::MirBuilder;
 
diff --git a/src/mir/builder/control_flow/exception/try_catch.rs b/src/mir/builder/control_flow/exception/try_catch.rs
index 568239a2..dd55cf4d 100644
--- a/src/mir/builder/control_flow/exception/try_catch.rs
+++ b/src/mir/builder/control_flow/exception/try_catch.rs
@@ -4,7 +4,7 @@
 //! including proper handling of deferred returns and cleanup blocks.
 
 use crate::ast::ASTNode;
-use crate::mir::builder::{Effect, EffectMask, MirInstruction, ValueId};
+use crate::mir::builder::{MirInstruction, ValueId};
 
 /// Control-flow: try/catch/finally
 ///
diff --git a/src/mir/builder/control_flow/mod.rs b/src/mir/builder/control_flow/mod.rs
index adf6ff65..1ffeaaf6 100644
--- a/src/mir/builder/control_flow/mod.rs
+++ b/src/mir/builder/control_flow/mod.rs
@@ -1,12 +1,43 @@
-//! Control-flow entrypoints (if/loop/try/throw) centralized here.
+//! Control-flow entrypoints for MIR builder.
+//!
+//! This module provides the main entry points for control flow constructs:
+//! - Block expressions
+//! - If/else conditionals
+//! - Loops
+//! - Try/catch/finally exception handling
+//! - Throw statements
+//!
+//! # Architecture
+//!
+//! Originally a monolithic 1,632-line file, this module has been modularized
+//! into 19 focused submodules for better maintainability and clarity:
+//!
+//! ## Submodules
+//!
+//! - `debug` - Debug utilities and tracing
+//! - `joinir` - JoinIR integration (patterns, routing, merge)
+//!   - `patterns` - Loop pattern implementations (3 patterns)
+//!   - `routing` - Pattern routing and dispatch
+//!   - `merge` - MIR block merging (5 phases)
+//! - `exception` - Exception handling (try/catch/throw)
+//! - `utils` - Utility functions (loop variable extraction)
+//!
+//! ## Modularization History
 //!
-//! This module is being modularized in phases:
 //! - Phase 1: Debug utilities (debug.rs) ✅
 //! - Phase 2: Pattern lowerers (joinir/patterns/) ✅
 //! - Phase 3: JoinIR routing (joinir/routing.rs) ✅
 //! - Phase 4: Merge implementation (joinir/merge/) ✅
 //! - Phase 5: Exception handling (exception/) ✅
 //! - Phase 6: Utility functions (utils.rs) ✅
+//! - Phase 7: Documentation and cleanup ✅
+//!
+//! # Design Philosophy
+//!
+//! All control flow implementations follow a delegation pattern:
+//! - Entry points in this file validate and route to submodules
+//! - Submodules implement the actual logic
+//! - Clear separation of concerns enables easier testing and modification
 
 use super::ValueId;
 use crate::ast::ASTNode;