From 7beec7ee8008c16ca8ad2a3708c6e70cb27e0503 Mon Sep 17 00:00:00 2001
From: HiranoMasaaki <lambda.groove@gmail.com>
Date: Sat, 3 Jan 2026 06:16:36 +0000
Subject: [PATCH] refactor(create-expert): document 4-level delegation depth
 architecture

Add Architecture Note explaining the intentional separation of concerns:
- Level 1: Orchestration (what to create)
- Level 2: Integration (coordinate testing types)
- Level 3: Stage management (functional vs usability)
- Level 4: Test execution (run and evaluate)

Closes #358
---
 .changeset/document-delegation-depth.md          | 11 +++++++++++
 apps/create-expert/src/lib/create-expert-toml.ts |  8 ++++++++
 2 files changed, 19 insertions(+)
 create mode 100644 .changeset/document-delegation-depth.md

diff --git a/.changeset/document-delegation-depth.md b/.changeset/document-delegation-depth.md
new file mode 100644
index 00000000..ba739f5d
--- /dev/null
+++ b/.changeset/document-delegation-depth.md
@@ -0,0 +1,11 @@
+---
+"create-expert": patch
+---
+
+Document 4-level delegation depth architecture
+
+Added Architecture Note explaining the intentional separation of concerns:
+- Level 1 (create-expert): Orchestration
+- Level 2 (integration-manager): Coordinate testing types
+- Level 3 (functional/usability-manager): Stage management
+- Level 4 (expert-tester): Test execution
diff --git a/apps/create-expert/src/lib/create-expert-toml.ts b/apps/create-expert/src/lib/create-expert-toml.ts
index a5fb3190..d77fc651 100644
--- a/apps/create-expert/src/lib/create-expert-toml.ts
+++ b/apps/create-expert/src/lib/create-expert-toml.ts
@@ -37,6 +37,14 @@ Coordinate the Expert creation process by delegating to specialized Experts.
 - Integration manager coordinates both functional and usability testing
 - You just orchestrate the high-level flow
 - The ecosystem should be immediately usable by fresh users
+
+## Architecture Note
+The 4-level delegation depth (create-expert → integration-manager → functional/usability-manager → expert-tester)
+is intentional for separation of concerns:
+- Level 1: Orchestration (what to create)
+- Level 2: Integration (coordinate testing types)
+- Level 3: Stage management (functional vs usability)
+- Level 4: Test execution (run and evaluate)
 `
 
 const PROPERTY_EXTRACTOR_INSTRUCTION = `You extract testable properties from user requirements.