| name | concept-extractor |
| description | Mine candidate domain concepts and their vocabulary from every naming source of a legacy system — database schema, UI labels, REST/URL paths, configuration, code identifiers, documentation. Produces a regenerable CONCEPTS.md (aliases, evidence, frequency, co-occurrence) and seeds a human-owned GLOSSARY.md with canonical terms, both in the analyzed project's migration/ folder. First step of a legacy-to-BCE migration; composes with bce and sbce. Invoke explicitly as /concept-extractor on the system to analyze. Not for mechanical 1:1 ports (use j2ee-migration) and not for carving business components — it only produces the vocabulary later steps consume. |
| disable-model-invocation | true |
Concept Extractor
Recover the domain language buried in a legacy system's names. The technical structure of overengineered systems lies about the domain — packages reflect patterns, not business capabilities. Names are where the original domain knowledge survived. Produce candidates for human review, never verdicts.
Workflow
- Inventory which naming sources exist in the system (see ranking below).
- Mine every source. Tokenize compound names:
CustomerContractValidationServiceFactoryImpl → Customer, Contract, Validation.
- Strip pattern noise using references/noise-words.md. Keep the discards for the noise report.
- Cluster aliases into one concept per meaning (Customer / Client / Kunde /
CUST). Expand abbreviations from surrounding context — column names, labels, Javadoc.
- Record co-occurrence: two concepts co-occur when they share a class, table, URL path, or UI view.
- Write
migration/CONCEPTS.md in the analyzed project — all pipeline artifacts live in this folder, never at the legacy project's root.
- Seed
migration/GLOSSARY.md if absent. If present, append proposals under ## Proposed — never modify existing entries.
Naming Sources — Ranked by Trustworthiness
Mine all that exist. When sources conflict, trust the higher-ranked one:
- Database schema — tables, columns, constraints. Survived every refactoring fashion; usually the most honest source.
- UI labels — JSP/JSF/HTML text, i18n bundles, report headers. Closest to the language the business actually speaks.
- External contracts — REST/URL paths, queue and topic names, WSDL, exchanged file names.
- Configuration keys, enum values, exception names.
- Code identifiers — packages, classes, methods, fields. Most numerous, least reliable.
- Comments, Javadoc, test names, documentation.
CONCEPTS.md Format
Regenerable, evidence-oriented, diffable. Use this structure:
# Concepts: <system name>
## Concepts
### <Concept>
- **Aliases:** <all forms found, incl. abbreviations>
- **Sources:** DB / UI / contracts / code — with concrete pointers (table, file, path)
- **Frequency:** <n> | **Confidence:** high | medium | low
- **Co-occurs with:** <Concept> (<count>), ...
## Co-occurrence
<table or Mermaid graph of concept pairs with counts>
## Noise Report
<stripped words with counts — makes the extraction auditable>
## Open Questions
### Q<n> —
Q-ids are stable across re-runs: never renumber, new questions get new ids. They are the contract concept-clarifier resolves against.
Confidence: high = present in several source kinds, medium = one kind with many occurrences, low = single source or unresolved abbreviation. Order concepts by frequency — the reader reviews the top entries carefully and skims the tail.
GLOSSARY.md Format
Human-owned, durable — the ubiquitous language of the future system. Seed one entry per high- and medium-confidence concept:
### <Concept>
**Definition (inferred):** <one sentence>. *(hypothesis — derived from <evidence>; confirm with domain expert)*
**Canonical term:** <term> — supersedes: <aliases>
**Related:** [[<Concept>]], [[<Concept>]]
Every definition is inferred from usage, not knowledge — mark it as a hypothesis until a human removes the marker. The canonical term is a naming decision for the generated code (entities, boundaries, REST paths, BC names); for mixed-language systems, pick one language and state it at the top of the glossary.
The glossary outlives migration/: its canonical terms feed the new system's sbce system doc and BC naming. It is authored here but meant to be promoted into the new system — the folder is disposable, the glossary is cargo. State this in the glossary header.
Rules
- Every claim carries an evidence pointer — review must be spot-checkable, not trust-based.
- All output goes to
migration/ — a well-known path is the contract downstream skills read from, and one folder keeps the legacy repo clean (one .gitignore line, one rm -r after migration).
- Never overwrite a human-edited file: regenerate
CONCEPTS.md to migration/CONCEPTS.new.md when the original was modified; only ever append to GLOSSARY.md.
- Confirmed glossary entries and its
## Decisions section are ground truth: on re-runs keep their merges, splits, and canonical terms, and do not re-open answered questions — resolved Q-ids stay resolved in CONCEPTS.new.md.
- Noise is contextual — a pattern word can be a domain term (Booking in payments, Position in trading). When a noise-list word appears in DB columns or UI labels, keep it as a concept.
- Do not carve business components or propose architecture — downstream skills (
bce, sbce) consume the output.
