concept-clarifier

Name: concept-clarifier
Author: AdamBien

40stars10forks

How to install concept-clarifier?

adambien/airails/concept-clarifier

$npx -y skills add AdamBien/airails --skill concept-clarifier

Installs into the current project.

Summary

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 wi

Files · 1

View on GitHub

SKILL.md

1	# Concept Clarifier
2
3	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.
4
5	## Inputs
6
7	Build one work queue from:
8
9	1. `migration/CONCEPTS.md` → `## Open Questions`, by Q-id.
10	2. Every `migration/GLOSSARY.md` entry still carrying a `(hypothesis …)` marker.
11	3. `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.
12
13	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.
14
15	## Mode Selection
16
17	First ask who answers:
18
19	- The person in this session → live interview.
20	- A remote domain expert → async questionnaire. This is the common case in real migrations.
21
22	If `migration/INTERVIEW.md` exists and contains filled-in answers, skip the question phase and fold back (below).
23
24	## Live Interview
25
26	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.
27
28	## Async Questionnaire
29
30	Generate `migration/INTERVIEW.md` from [references/interview-template.md](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.
31
32	On fold-back, parse each answered block; leave unanswered blocks untouched. Partial answers are normal — fold what exists.
33
34	## Fold-Back Rules
35
36	Every confirmed answer lands in `migration/GLOSSARY.md`:
37
38	- Remove the `(hypothesis …)` marker; stamp provenance: `confirmed: <name>, <YYYY-MM-DD>`.
39	- 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.
40	- 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.
41	- In `CONCEPTS.md`, mark the resolved question: `~~Q3: …~~ → answered, see GLOSSARY.md`. Annotate, never delete — the audit trail must survive.
42	- Edit only the affected entries. Never regenerate the glossary; it is human-owned.
43
44	## Rules
45
46	- Never answer a question yourself, however obvious — plausible self-answers are how hypotheses masquerade as facts.
47	- Unanswered and deferred questions remain open; re-runs pick them up again.
48	- Record who answered, always — provenance is what separates a confirmed term from a guess with confidence.

People who liked this also viewed

6 picks

Type

concept-clarifier

40stars10forks

View on GitHub

How to install concept-clarifier?

adambien/airails/concept-clarifier

$npx -y skills add AdamBien/airails --skill concept-clarifier

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Concept Clarifier
2
3	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.
4
5	## Inputs
6
7	Build one work queue from:
8
9	1. `migration/CONCEPTS.md` → `## Open Questions`, by Q-id.
10	2. Every `migration/GLOSSARY.md` entry still carrying a `(hypothesis …)` marker.
11	3. `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.
12
13	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.
14
15	## Mode Selection
16
17	First ask who answers:
18
19	- The person in this session → live interview.
20	- A remote domain expert → async questionnaire. This is the common case in real migrations.
21
22	If `migration/INTERVIEW.md` exists and contains filled-in answers, skip the question phase and fold back (below).
23
24	## Live Interview
25
26	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.
27
28	## Async Questionnaire
29
30	Generate `migration/INTERVIEW.md` from [references/interview-template.md](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.
31
32	On fold-back, parse each answered block; leave unanswered blocks untouched. Partial answers are normal — fold what exists.
33
34	## Fold-Back Rules
35
36	Every confirmed answer lands in `migration/GLOSSARY.md`:
37
38	- Remove the `(hypothesis …)` marker; stamp provenance: `confirmed: <name>, <YYYY-MM-DD>`.
39	- 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.
40	- 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.
41	- In `CONCEPTS.md`, mark the resolved question: `~~Q3: …~~ → answered, see GLOSSARY.md`. Annotate, never delete — the audit trail must survive.
42	- Edit only the affected entries. Never regenerate the glossary; it is human-owned.
43
44	## Rules
45
46	- Never answer a question yourself, however obvious — plausible self-answers are how hypotheses masquerade as facts.
47	- Unanswered and deferred questions remain open; re-runs pick them up again.
48	- Record who answered, always — provenance is what separates a confirmed term from a guess with confidence.

People who liked this also viewed

6 picks

Type