From fc03a138361dcbc08214376781bceda710738873 Mon Sep 17 00:00:00 2001
From: HiranoMasaaki <lambda.groove@gmail.com>
Date: Sat, 3 Jan 2026 05:32:39 +0000
Subject: [PATCH] fix(create-expert): improve description clarity for internal
 experts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Update descriptions to include input expectations and output format:

- property-extractor: specify it returns structured properties list
- ecosystem-builder: specify it takes properties and returns TOML
- integration-manager: specify parallel testing and report format
- functional-manager: specify test types and report format
- usability-manager: specify ecosystem tests and report format
- expert-tester: specify required inputs (stage, expert, properties, cases)

Follows docs guidance: "A good description tells potential callers
what this Expert can do, when to use it, and what to include."

Closes #352

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 .changeset/improve-descriptions.md               | 14 ++++++++++++++
 apps/create-expert/src/lib/create-expert-toml.ts | 12 ++++++------
 2 files changed, 20 insertions(+), 6 deletions(-)
 create mode 100644 .changeset/improve-descriptions.md

diff --git a/.changeset/improve-descriptions.md b/.changeset/improve-descriptions.md
new file mode 100644
index 00000000..c7a3770b
--- /dev/null
+++ b/.changeset/improve-descriptions.md
@@ -0,0 +1,14 @@
+---
+"create-expert": patch
+---
+
+Improve description clarity for internal PBT framework experts
+
+Each description now includes:
+- What the expert does
+- What input to provide
+- What output to expect
+
+This follows the documentation guidance: "A good description tells
+potential callers what this Expert can do, when to use it, and what
+to include in the query."
diff --git a/apps/create-expert/src/lib/create-expert-toml.ts b/apps/create-expert/src/lib/create-expert-toml.ts
index d34368f0..c355d11a 100644
--- a/apps/create-expert/src/lib/create-expert-toml.ts
+++ b/apps/create-expert/src/lib/create-expert-toml.ts
@@ -623,7 +623,7 @@ pick = ["attemptCompletion"]
 
 [experts."property-extractor"]
 version = "1.0.0"
-description = "Extracts testable properties from user requirements"
+description = "Extracts testable properties from user requirements. Provide requirements text. Returns user properties, Perstack properties, usability properties, and external dependencies."
 instruction = '''
 ${PROPERTY_EXTRACTOR_INSTRUCTION}
 '''
@@ -638,7 +638,7 @@ pick = ["attemptCompletion"]
 
 [experts."ecosystem-builder"]
 version = "1.0.0"
-description = "Creates Expert ecosystem (main + demo + setup + doctor)"
+description = "Creates Expert ecosystem from properties. Provide extracted properties and requirements. Returns perstack.toml with main, demo, and optionally setup/doctor experts."
 instruction = '''
 ${ECOSYSTEM_BUILDER_INSTRUCTION}
 '''
@@ -653,7 +653,7 @@ pick = ["readTextFile", "appendTextFile", "attemptCompletion"]
 
 [experts."integration-manager"]
 version = "1.0.0"
-description = "Orchestrates coordinated functional and usability testing"
+description = "Orchestrates functional and usability testing in parallel. Provide ecosystem info and properties. Returns integration report with scores and recommendations."
 instruction = '''
 ${INTEGRATION_MANAGER_INSTRUCTION}
 '''
@@ -669,7 +669,7 @@ pick = ["attemptCompletion"]
 
 [experts."functional-manager"]
 version = "1.0.0"
-description = "Manages all functional PDCA cycles (happy-path, unhappy-path, adversarial)"
+description = "Runs happy-path, unhappy-path, and adversarial tests. Provide properties and ecosystem. Returns functional test report with pass/fail counts."
 instruction = '''
 ${FUNCTIONAL_MANAGER_INSTRUCTION}
 '''
@@ -685,7 +685,7 @@ pick = ["attemptCompletion"]
 
 [experts."usability-manager"]
 version = "1.0.0"
-description = "Manages usability PDCA cycle for expert ecosystem"
+description = "Tests usability of expert ecosystem (demo, setup, doctor, errors). Provide ecosystem and properties. Returns usability report."
 instruction = '''
 ${USABILITY_MANAGER_INSTRUCTION}
 '''
@@ -701,7 +701,7 @@ pick = ["attemptCompletion"]
 
 [experts."expert-tester"]
 version = "1.0.0"
-description = "Executes tests and reports property-wise results"
+description = "Executes tests against experts. Provide stage, expert name, properties, and test cases. Returns property-wise pass/fail results."
 instruction = '''
 ${EXPERT_TESTER_INSTRUCTION}
 '''