Skip to content

Refactor: create-expert coordinator lacks error recovery guidance #362

@FL4TLiN3

Description

@FL4TLiN3

Description

The create-expert coordinator instruction doesn't specify how to handle failures from delegated experts.

Current Behavior

CREATE_EXPERT_INSTRUCTION (lines 13-40) describes the workflow:

## Workflow

1. **Extract Properties**: Delegate to \`property-extractor\` with user requirements
   - Get back: user properties + Perstack properties + usability properties + external dependencies

2. **Build Expert Ecosystem**: Delegate to \`ecosystem-builder\` with properties
   - Get back: perstack.toml with Expert ecosystem (main + demo + setup + doctor)

3. **Integration Testing**: Delegate to \`integration-manager\`
   ...

4. **Generate Report**: Delegate to \`report-generator\`
   ...

Missing

No guidance on:

  1. What happens if property-extractor fails to extract meaningful properties?
  2. What happens if ecosystem-builder produces invalid TOML?
  3. What happens if integration-manager reports test failures?
  4. Should create-expert retry? Ask for clarification? Modify the ecosystem?

Expected Behavior

Per docs/understanding-perstack/experts.md:

When a Delegated Expert fails (unrecoverable error), the Job continues:

  1. The failed Run is marked as stoppedByError
  2. The error is returned to the Coordinator as the delegation result
  3. The Coordinator decides how to handle it (retry, try different Expert, give up)

The coordinator should have explicit error handling policies.

Target State

## Error Handling

If property-extractor fails:
- Ask user to clarify requirements
- Retry with more specific prompts

If ecosystem-builder produces invalid output:
- Request ecosystem-builder to fix the issue
- Retry up to 2 times before asking user for help

If integration-manager reports failures:
- Pass failure details back to ecosystem-builder for fixes
- Iterate until tests pass or max retries reached

If report-generator fails:
- Retry once, then provide raw test results to user

Affected Areas

  • apps/create-expert/src/lib/create-expert-toml.ts:13-40 (CREATE_EXPERT_INSTRUCTION)

Acceptance Criteria

  • Add error handling policies for each delegation step
  • Specify retry behavior
  • Define when to escalate to user

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