Train Orchestrator

train-orchestrator

Phase 1 of pair-goal. Turns a vague "make X better" into a sharp, verifiable improvement target, written to .pairgoal/UNDERSTANDING.md.

How this differs from plain brainstorming

Plain brainstorming assumes a greenfield idea and explores what to build. Here you assume the user already has something and wants it improved — so you explore what's wrong now and what better looks like. The bias is toward finding the deficiency and a measurable signal, not inventing scope.

The one thing that matters most

write-goal (the next phase) needs a transcript-demonstrable success signal — because /goal's evaluator only reads the conversation, it can't run tools. So your job here is not done until you have a check whose output Claude can show: a test that exits 0, a benchmark number a script prints, a file count, a lint result. "Cleaner code" or "faster" without a number is not a signal — push until it's concrete.

Process

Explore the target first (read the file/module, recent commits, any existing tests or benchmarks), then ask one question at a time, multiple-choice when possible. Cover, in order:

1. What, exactly, are we improving? The specific file/module/endpoint/behavior. Locate it in the repo.
2. What's wrong or insufficient now? Get evidence, not vibes — a slow number, a failing case, a duplicated block, an error rate. If the user can't name it, help measure it.
3. What does "better" mean? The concrete target state.
4. **How will we prove it's better?** The success signal — measurable and transcript-demonstrable. This is the question to be stubborn about.
5. What must not change? Constraints: public API, dependencies, behavior that other code relies on.
6. What's explicitly out of scope? Guard against scope creep — YAGNI.

If the request bundles several independent improvements, say so and pick one to pursue now; the others can be separate pair-goal runs.

Output

Write .pairgoal/UNDERSTANDING.md using the template in [../pair-goal/reference/file-formats.md](../pair-goal/reference/file-formats.md). Then show the user a 5-line recap (target · deficiency · what better means · success signal · key constraint) and confirm it's right before handing to write-goal.

If invoked standalone (not by the pair-goal orchestrator), end by suggesting: "Next: write-goal to turn this into a /goal condition."

Don't

• Don't propose the fix here — that's the racers' job in pair-iterate. Stay on what and how we'll know, not how.
• Don't accept an unmeasurable success signal. If you can't make it transcript-demonstrable, say so explicitly in UNDERSTANDING.md so write-goal can flag it.
• Don't over-question a clear, small ask. Two or three sharp questions can be enough.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ccomkhj
• Source: ccomkhj/skills
• License: MIT

Install and usage instructions live in the source repository linked above.