Refactor: Improve description clarity for create-expert internal experts #352
Description
Description
Several internal experts in create-expert-toml.ts have descriptions that don't follow the documentation guidance for good descriptions. According to docs/understanding-perstack/experts.md:
A good description tells potential callers what this Expert can do, when to use it, and what to include in the query.
Current State
| Expert | Current Description | Issue |
|---|---|---|
property-extractor |
"Extracts testable properties from user requirements" | Doesn't specify expected input format or what is returned |
ecosystem-builder |
"Creates Expert ecosystem (main + demo + setup + doctor)" | Doesn't specify what input is expected (properties? requirements?) |
functional-manager |
"Manages all functional PDCA cycles (happy-path, unhappy-path, adversarial)" | Doesn't specify what to include in the query |
usability-manager |
"Manages usability PDCA cycle for expert ecosystem" | Doesn't specify expected inputs |
expert-tester |
"Executes tests and reports property-wise results" | Doesn't specify what inputs are needed (stage, expert name, properties, test cases) |
Target State
Each description should include:
- What the expert does
- What input to provide in the query
- What output to expect
Example improvement for property-extractor:
"Extracts testable properties from requirements. Provide user requirements text. Returns structured list of user properties, Perstack properties, usability properties, and external dependencies."
Affected Areas
apps/create-expert/src/lib/create-expert-toml.ts(description strings for each expert)
Acceptance Criteria
- Each description includes expected input format
- Each description includes what output to expect
- Descriptions remain concise (under 2048 chars)