Skip to content

Refactor: simplify verbose descriptions in create-expert delegates #377

@FL4TLiN3

Description

@FL4TLiN3

Description

Several internal experts have overly verbose description fields that include implementation details. Per the documentation, description is exposed to delegators as tool descriptions and should be concise.

Current State

[experts."property-extractor"]
description = "Extracts testable properties from user requirements. Provide requirements text. Returns user properties, Perstack properties, usability properties, and external dependencies."

[experts."ecosystem-builder"]
description = "Creates Expert ecosystem from properties. Provide extracted properties and requirements. Returns perstack.toml with main, demo, and optionally setup/doctor experts."

[experts."integration-manager"]
description = "Orchestrates functional and usability testing in parallel. Provide ecosystem info and properties. Returns integration report with scores and recommendations."

These descriptions are 20-30+ words and include:

  • Input format instructions ("Provide requirements text")
  • Output format details ("Returns user properties, Perstack properties...")
  • Implementation details ("in parallel")

Target State

From docs/making-experts/README.md:

Write description for the delegator — what can I ask for? What will I get back?

Descriptions should be 1-2 sentences focused on capability:

[experts."property-extractor"]
description = "Extracts testable properties from user requirements"

[experts."ecosystem-builder"]  
description = "Creates Expert ecosystem with main, demo, setup, and doctor experts"

[experts."integration-manager"]
description = "Coordinates functional and usability testing, returns quality assessment"

Input/output details belong in instruction, not description.

Affected Experts

  • property-extractor
  • ecosystem-builder
  • integration-manager
  • functional-manager
  • usability-manager
  • expert-tester

Affected Areas

  • apps/create-expert/src/lib/create-expert-toml.ts

Acceptance Criteria

  • No behavior changes
  • Descriptions are concise (under 100 characters ideally)
  • Input/output details moved to instruction where needed
  • Each description answers: "what can I ask for?"

Metadata

Metadata

Assignees

No one assigned

    Labels

    create-expertcreate-expert CLI packagerefactorCode improvement without behavior change

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions