concept-annotator

Name: concept-annotator
Author: AdamBien

40stars10forks

How to install concept-annotator?

adambien/airails/concept-annotator

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

Installs into the current project.

Summary

Project the mined domain concepts into the codebase — write one package-info.java (Java 25 /// Markdown doc) per legacy package with the concepts living there, candidate-BC leaning, and refactoring hints, consuming migration/CONCEPTS.md, GLOSSARY.md, and CARVING.md when present.

Files · 1

View on GitHub

SKILL.md

1	# Concept Annotator
2
3	Carry the captured domain knowledge into the code itself. Every legacy package becomes self-describing — which concepts live here, where the package is heading, what the naming evidence suggests — in the exact file where the future sbce spec will live. A developer opening the package sees the migration state without leaving the IDE; an annotated system cannot quietly pretend the migration is done.
4
5	## Inputs
6
7	- `migration/GLOSSARY.md` — canonical terms and `## Decisions`: ground truth.
8	- `migration/CONCEPTS.md` — evidence pointers mapping concepts to packages and classes.
9	- `migration/CARVING.md` — when present, supplies target BC and moves per package.
10
11	Prefer running after `/concept-clarifier`; if glossary entries are still hypothesis-marked, carry the marker into the annotation verbatim — never launder a hypothesis into a fact.
12
13	## Workflow
14
15	1. List the Java packages of the source tree.
16	2. Map concepts to packages via the CONCEPTS.md evidence pointers; note the local aliases per package.
17	3. Per package, write `package-info.java` — or update only the owned section of an existing one — from [references/package-info-template.md](references/package-info-template.md).
18	4. Verify the build stays green: annotations are docs, never behavior.
19
20	## Annotation Content
21
22	Per package, inside the owned section:
23
24	- Concepts — canonical term plus the aliases as they appear locally (`Contract — here: Cntrct, VTRG`).
25	- Candidate BC — single lowercase glossary token, or `unassigned`. With `CARVING.md` present: Target BC plus the move rows affecting this package.
26	- Refactoring hints — evidence-backed suggestions: mixed concepts → split candidate, names to rename to canonical terms, apparent boundary/control/entity leaning per class.
27	- See — pointers to the `migration/` artifacts and open Q-ids touching this package.
28
29	## Rules
30
31	- Docs only — never touch code, imports, or resources. The smallest possible change to a runnable system is no change.
32	- Own only the marked section (`## Migration Notes (concept-annotator)`). Preserve existing package-info content and hand edits outside the marker; re-runs regenerate only the owned section.
33	- Open every generated section with the disclaimer `Migration notes — not an sbce spec.` — sbce treats package docs as authoritative boundary contracts, and these hints must never be mistaken for one. `/sbce` later replaces the notes with a real spec.
34	- Hints are candidates, not verdicts: phrase as evidence-backed suggestions, never contradict the glossary, carry hypothesis markers and Q-ids instead of resolving them.

People who liked this also viewed

6 picks

Type

concept-annotator

40stars10forks

View on GitHub

How to install concept-annotator?

adambien/airails/concept-annotator

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

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Concept Annotator
2
3	Carry the captured domain knowledge into the code itself. Every legacy package becomes self-describing — which concepts live here, where the package is heading, what the naming evidence suggests — in the exact file where the future sbce spec will live. A developer opening the package sees the migration state without leaving the IDE; an annotated system cannot quietly pretend the migration is done.
4
5	## Inputs
6
7	- `migration/GLOSSARY.md` — canonical terms and `## Decisions`: ground truth.
8	- `migration/CONCEPTS.md` — evidence pointers mapping concepts to packages and classes.
9	- `migration/CARVING.md` — when present, supplies target BC and moves per package.
10
11	Prefer running after `/concept-clarifier`; if glossary entries are still hypothesis-marked, carry the marker into the annotation verbatim — never launder a hypothesis into a fact.
12
13	## Workflow
14
15	1. List the Java packages of the source tree.
16	2. Map concepts to packages via the CONCEPTS.md evidence pointers; note the local aliases per package.
17	3. Per package, write `package-info.java` — or update only the owned section of an existing one — from [references/package-info-template.md](references/package-info-template.md).
18	4. Verify the build stays green: annotations are docs, never behavior.
19
20	## Annotation Content
21
22	Per package, inside the owned section:
23
24	- Concepts — canonical term plus the aliases as they appear locally (`Contract — here: Cntrct, VTRG`).
25	- Candidate BC — single lowercase glossary token, or `unassigned`. With `CARVING.md` present: Target BC plus the move rows affecting this package.
26	- Refactoring hints — evidence-backed suggestions: mixed concepts → split candidate, names to rename to canonical terms, apparent boundary/control/entity leaning per class.
27	- See — pointers to the `migration/` artifacts and open Q-ids touching this package.
28
29	## Rules
30
31	- Docs only — never touch code, imports, or resources. The smallest possible change to a runnable system is no change.
32	- Own only the marked section (`## Migration Notes (concept-annotator)`). Preserve existing package-info content and hand edits outside the marker; re-runs regenerate only the owned section.
33	- Open every generated section with the disclaimer `Migration notes — not an sbce spec.` — sbce treats package docs as authoritative boundary contracts, and these hints must never be mistaken for one. `/sbce` later replaces the notes with a real spec.
34	- Hints are candidates, not verdicts: phrase as evidence-backed suggestions, never contradict the glossary, carry hypothesis markers and Q-ids instead of resolving them.

People who liked this also viewed

6 picks

Type