grove-glossary

$grove glossary

Scan project artifacts for candidate domain terms and propose additions to .cocoplus/grove/language/glossary.md. Developer reviews and confirms each proposed entry before it is written.

Preconditions

• .cocoplus/ must be initialized
• At least one of: lifecycle/spec.md, flow.json, lifecycle/plan.md, prompts/*.md, or CocoCupper findings must exist

Step-by-Step Behavior

1. Verify initialization: Check .cocoplus/ exists. If not, output: "CocoPlus not initialized. Run $pod init first." and exit.

2. Create glossary directory: Ensure .cocoplus/grove/language/ exists. Create if missing.

1. Read existing glossary: Read .cocoplus/grove/language/glossary.md if it exists. Extract already-defined terms and aliases using case-insensitive normalization:

   • Trim leading/trailing whitespace
   • Collapse repeated spaces
   • Compare lowercase term text
   • Compare aliases as duplicate keys for the canonical term

2. Scan project artifacts for candidate terms:

   • lifecycle/spec.md — function names, capability descriptions, domain nouns
   • .cocoplus/flow.json — stage names and descriptions
   • lifecycle/plan.md — decision terms, evaluation references
   • lifecycle/discuss.md — threshold names, methodology terms
   • .cocoplus/prompts/*.md — AI function input/output descriptions
   • .cocoplus/grove/cupper-findings.md — pattern names, anti-pattern terms
   • .cocoplus/map/coco-map.json — capability names from domain section (if exists)

3. Extract candidate terms: Look for multi-word noun phrases that appear as key concepts:

   • Function names used as domain concepts (e.g., "sentiment score", "churn propensity")
   • Metric and threshold names (e.g., "accuracy baseline", "gold standard dataset")
   • Process terms that appear in multiple artifacts (e.g., "evaluation harness", "prompt iteration")
   • Exclude generic technical terms (SQL keywords, standard Snowflake function names)

4. Filter known terms: Remove any candidates that already appear in the existing glossary as either a canonical term or an alias. If a candidate duplicates an alias but adds useful context, propose an update to the existing entry instead of a new term.

5. Present candidates to developer one at a time (or in a numbered list for batch review):

   Proposed glossary additions ([N] candidates):
   
   [N] terms found that are not yet in the glossary.
   
   1. "customer churn propensity"
      Appears in: spec.md, prompts/classifier-v2.md
      Proposed definition: [AI-inferred brief definition based on context]
      Aliases (optional): churn score, propensity score
      Associated functions: [function names where this term appears]
      
      Accept? [Y to add / N to skip / E to edit definition]
   
   2. "gold standard dataset"
      ...
   

6. For each accepted entry or update: Write to .cocoplus/grove/language/glossary.md in the following format:

   ## [Term]
   
   **Definition:** [definition text]
   **Aliases:** [alias1, alias2] (or "None")
   **Associated functions:** [list of function names]
   **Added:** [ISO8601 date]
   

   If updating an existing term, preserve its current definition unless the developer explicitly accepts the edited definition. Append new aliases/functions without duplicating existing values.

7. Create git commit after all accepted entries are written: feat(grove): add [N] glossary terms

8. Confirm to developer:

   ✓ Glossary updated
   [N] terms added. [M] skipped.
   
   View glossary: $grove glossary view
   Glossary is available to CocoScout for context loading.
   

Empty results case

If no new candidates are found beyond existing glossary terms:

No new domain terms found.
[N] terms already in glossary.

Run $grove glossary view to see existing entries.

Error Cases

• No source artifacts found: Output warning and list which artifacts are missing; suggest running $spec first
• Cannot write glossary file: Output filesystem error; do not commit partial entries
• Developer skips all candidates: Output: "No terms added. Run again after adding more project artifacts."

Exit Criteria

This skill is complete when:

• Candidate terms have been presented for developer review
• Accepted terms are written to glossary.md
• Git commit is created (if at least one term was added)

Anti-Rationalization

Do NOT:

• Auto-write any term without developer confirmation
• Add generic SQL/Snowflake technical terms (SELECT, CREATE, AI_CLASSIFY without domain context)
• Fail silently if no artifacts are found — always report what was scanned
• Create a new glossary entry when the term already exists as an alias or case-only variant