| name | concept-clarifier |
| description | Resolve the open questions and hypothesis-marked glossary definitions produced by concept-extractor and bc-carver together with a human domain expert — via live interview or an async questionnaire (migration/INTERVIEW.md) — and fold confirmed answers into migration/GLOSSARY.md with provenance. Second step of a legacy-to-BCE migration; composes with concept-extractor. Invoke explicitly as /concept-clarifier in the analyzed project. Not for scoping a task or gathering requirements for a request — use clarify for that. |
| disable-model-invocation | true |
Concept Clarifier
Turn the extractor's hypotheses into confirmed domain knowledge. Machines mined the candidates; only a human who knows the business can settle them. Never invent an answer — an open question folded back wrong poisons every downstream step.
Inputs
Build one work queue from:
migration/CONCEPTS.md → ## Open Questions, by Q-id.- Every
migration/GLOSSARY.md entry still carrying a (hypothesis …) marker.
migration/CARVING.md → ## Open Questions, when present — BC-assignment questions share the same Q-id space and resolve through the same flow; their answers land in GLOSSARY.md ## Decisions keyed by Q-id.
Group the queue by theme: synonym merges, homonym splits, abbreviation expansions, canonical-term and language choices, BC assignments. Do not mine the codebase — evidence shown to the expert comes verbatim from the CONCEPTS.md pointers; if evidence is missing, that is an extractor defect, not a reason to search.
Mode Selection
First ask who answers:
- The person in this session → live interview.
- A remote domain expert → async questionnaire. This is the common case in real migrations.
If migration/INTERVIEW.md exists and contains filled-in answers, skip the question phase and fold back (below).
Live Interview
Use AskUserQuestion, one theme per round, max 4 questions per call. Make options enumerable where possible — "Same concept / Different concepts / Depends" — with the evidence pointers in the option descriptions; free-form answers arrive via "Other". After each round, fold back immediately, then continue. Stop when the queue is empty or the user defers the remainder — deferred questions stay open.
Async Questionnaire
Generate migration/INTERVIEW.md from references/interview-template.md: one block per question with Q-id, question, evidence, checkbox options, free-text line, and an "answered by" line. Tell the user to send it to the expert and re-run /concept-clarifier when it comes back filled in.
On fold-back, parse each answered block; leave unanswered blocks untouched. Partial answers are normal — fold what exists.
Fold-Back Rules
Every confirmed answer lands in migration/GLOSSARY.md:
- Remove the
(hypothesis …) marker; stamp provenance: confirmed: <name>, <YYYY-MM-DD>.
- Apply consequences, not just the words: merge alias clusters into one entry, split a homonym into two entries, correct the canonical term, update
Related: links.
- Decisions with no glossary entry of their own (e.g. "keep as two concepts", "German is the canonical language") go into a
## Decisions section, one line per Q-id. The glossary is the single durable decision store that extractor re-runs consult.
- In
CONCEPTS.md, mark the resolved question: ~~Q3: …~~ → answered, see GLOSSARY.md. Annotate, never delete — the audit trail must survive.
- Edit only the affected entries. Never regenerate the glossary; it is human-owned.
Rules
- Never answer a question yourself, however obvious — plausible self-answers are how hypotheses masquerade as facts.
- Unanswered and deferred questions remain open; re-runs pick them up again.
- Record who answered, always — provenance is what separates a confirmed term from a guess with confidence.
