Skip to content

Refactor: functional-manager/usability-manager have overlapping PDCA phase structure #356

@FL4TLiN3

Description

@FL4TLiN3

Description

Both functional-manager and usability-manager describe their own PDCA (Plan-Do-Check-Act) cycles in detail, but the structure is nearly identical with only the test scenarios differing. This creates maintenance burden and potential inconsistency.

Current State

functional-manager (lines 269-348):

### Phase 1: Happy-Path Testing
#### Plan
Identify test cases for happy-path...
#### Do
Delegate to \`expert-tester\` with...
#### Check & Act
Review results, fix any failures...

usability-manager (lines 419-464):

### Plan
Define usability test scenarios...
### Do
Delegate to \`expert-tester\` with...
### Check
Verify usability properties...
### Act
If any property fails...

The structure is essentially the same with different domain content.

Issues

  1. Duplication: Both managers describe the same PDCA workflow pattern
  2. Inconsistency risk: Updating one may leave the other outdated
  3. Best practices violation: This is procedural ("Phase 1", "Plan", "Do", "Check", "Act") rather than declarative

Target State

Following best practices, these should focus on domain knowledge rather than procedure:

functional-manager:

You manage functional quality verification.

## Test Categories
- Happy-path: Valid inputs, expected queries
- Unhappy-path: Empty data, invalid formats, edge cases  
- Adversarial: Prompt injection, path traversal, role confusion

## Quality Criteria
[Define what passes/fails for each category]

usability-manager:

You manage usability verification.

## Test Categories
- Fresh user success: Zero-knowledge usability
- Demo functionality: Works without configuration
- Setup efficiency: Completes in < 2 minutes
- Error guidance: All errors include "To fix:" steps

## Quality Criteria
[Define what passes/fails for each category]

Affected Areas

  • apps/create-expert/src/lib/create-expert-toml.ts:269-348 (FUNCTIONAL_MANAGER_INSTRUCTION)
  • apps/create-expert/src/lib/create-expert-toml.ts:419-464 (USABILITY_MANAGER_INSTRUCTION)

Acceptance Criteria

  • Remove procedural PDCA phase language
  • Focus on domain knowledge (what to test, quality criteria)
  • Trust the LLM to figure out the testing workflow

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