57 lines
2.3 KiB
Markdown
57 lines
2.3 KiB
Markdown
---
|
|
description: Propose a new glossary term — drafts an entry in .ontology/glossary.ncl
|
|
argument-hint: "<new-term-id> [hint about what it means]"
|
|
allowed-tools: Bash, Read, Edit
|
|
---
|
|
|
|
# Propose a new glossary term
|
|
|
|
You are about to add a **draft** entry to the project glossary at
|
|
`.ontology/glossary.ncl`.
|
|
|
|
## Discovery first
|
|
|
|
1. Run `./ontoref describe term <id> --fmt json 2>/dev/null` to verify the
|
|
term doesn't already exist (under any alias). If it returns
|
|
`{ "found": false }` proceed; otherwise show the existing entry and stop.
|
|
2. Search the codebase / ontology for context before drafting:
|
|
- `rg -i "<keyword>" .ontology/ adrs/ reflection/`
|
|
- Identify whether the term originates from an Axiom, Tension, Practice,
|
|
ADR, Schema, Module, or is External folklore.
|
|
|
|
## Draft fields (REQUIRED)
|
|
|
|
Ask the user (or infer when obvious) for:
|
|
|
|
- `id` — kebab-case unique identifier
|
|
- `name` — display label, EN + ES
|
|
- `category` — one of: `'Discipline`, `'Concept`, `'Practice`, `'Artifact`,
|
|
`'Procedure`, `'Tension`, `'Antipattern`
|
|
- `definition` — first sentence is the standalone definition, both EN and ES
|
|
- `origin` — `{ kind = 'Axiom|'Tension|'Practice|'Adr|'Schema|'Module|'Crate|'External, ref = "<id-or-path>" }`
|
|
- `related_terms` / `related_nodes` (optional but encouraged)
|
|
- `examples` / `forbidden` (optional, both EN and ES if provided)
|
|
|
|
## Important rules
|
|
|
|
- Always set `verified = false` (DRAFT) — the user explicitly promotes via
|
|
`verified = true` after review.
|
|
- DO NOT touch `reflection/defaults/glossary.ncl` (that file is the protocol
|
|
seed, propagated to consumer projects via migration). Project-specific
|
|
terms go in `.ontology/glossary.ncl::project_terms`.
|
|
- DO NOT invent an origin. If unclear, ask the user or use
|
|
`{ kind = 'External, ref = "" }`.
|
|
- All natural-language content goes in both `en` and `es` keys. If a translation
|
|
is missing, leave the other lang empty (`""`) rather than copy-paste.
|
|
|
|
## After drafting
|
|
|
|
1. Show the user the NCL block you propose to add.
|
|
2. Wait for confirmation.
|
|
3. Append the block to the `project_terms` array in
|
|
`.ontology/glossary.ncl`.
|
|
4. Run `nickel export --import-path . --format json .ontology/glossary.ncl > /dev/null`
|
|
to verify it parses; report exit code.
|
|
5. Run `./ontoref describe term <new-id>` to confirm it reads back correctly.
|
|
|
|
Arguments received: `$ARGUMENTS`
|