arckit-glossary

name	arckit-glossary
description	Generate a consolidated project glossary of terms, acronyms, and definitions from existing artifacts

You are helping an enterprise architect create a Project Glossary document. This document extracts and consolidates all terminology, acronyms, abbreviations, and definitions from existing project artifacts into a single authoritative reference.

User Input

$ARGUMENTS

Prerequisites: Read Artifacts

Note: Before generating, scan projects/ for existing project directories. For each project, list all ARC-*.md artifacts, check external/ for reference documents, and check 000-global/ for cross-project policies. If no external docs exist but they would improve output, ask the user.

RECOMMENDED (read if available, note if missing):

• REQ (Requirements Specification) — Extract: Domain terminology, requirement ID prefixes (BR/FR/NFR/INT/DR), technical terms, business terms, acronyms used in requirements
  • If missing: Note that requirements terminology is unavailable; glossary will have limited domain coverage
• DATA (Data Model) — Extract: Entity names, attribute definitions, data types, relationship terminology, cardinality terms
  • If missing: Note that data model terminology is unavailable; glossary will lack entity/attribute definitions

OPTIONAL (read if available, skip silently if missing):

• STKE (Stakeholder Analysis) — Extract: Stakeholder role titles, organizational terms, governance bodies, engagement terminology
• PRIN (Architecture Principles, in 000-global) — Extract: Principle names, governance terminology, compliance terms
• SOBC (Strategic Outline Business Case) — Extract: Financial/business terms, investment terminology, benefits realisation terms
• RSCH (Research Report) — Extract: Technology terms, vendor-specific terminology, product names, industry standards
• ADR (Architecture Decision Records) — Extract: Decision context terminology, architectural pattern names, technology choices
• STRAT (Architecture Strategy) — Extract: Strategic themes, capability terms, maturity model terminology
• RISK (Risk Register) — Extract: Risk categories, mitigation terms, likelihood/impact terminology

Prerequisites 1b: Read external documents and policies

• Read any external documents listed in the project context (external/ files) — extract domain-specific terminology, organizational jargon, policy terms
• Read any enterprise standards in projects/000-global/external/ — extract enterprise-wide terminology, cross-project terms
• If no external docs found but they would improve the output, ask: "Do you have any existing glossaries, data dictionaries, or terminology standards? I can read PDFs and images directly. Place them in projects/{project-dir}/external/ and re-run, or skip."
• Citation traceability: When referencing content from external documents, follow the citation instructions in .arckit/references/citation-instructions.md. Place inline citation markers (e.g., [PP-C1]) next to findings informed by source documents and populate the "External References" section in the template.

Instructions

1. Identify or Create Project

Identify the target project from the hook context. If the user specifies a project that doesn't exist yet, create a new project:

1. Use Glob to list projects/*/ directories and find the highest NNN-* number (or start at 001 if none exist)
2. Calculate the next number (zero-padded to 3 digits, e.g., 002)
3. Slugify the project name (lowercase, replace non-alphanumeric with hyphens, trim)
4. Use the Write tool to create projects/{NNN}-{slug}/README.md with the project name, ID, and date — the Write tool will create all parent directories automatically
5. Also create projects/{NNN}-{slug}/external/README.md with a note to place external reference documents here
6. Set PROJECT_ID = the 3-digit number, PROJECT_PATH = the new directory path

2. Read Glossary Template

Load the glossary template structure:

Read the template (with user override support):

• First, check if .arckit/templates-custom/glossary-template.md exists in the project root
• If found: Read the user's customized template (user override takes precedence)
• If not found: Read .arckit/templates/glossary-template.md (default)

Tip: Users can customize templates with $arckit-customize glossary

3. Extract Terms from Artifacts

Systematically scan all available artifacts and extract:

• Domain-specific terms — Business and technical terms with definitions inferred from context
• Acronyms and abbreviations — Every acronym used in any artifact, with full expansion
• Technical standards referenced — Standard names with versions and URLs where available (e.g., ISO 27001:2022, WCAG 2.2)
• Requirement ID prefix meanings — BR = Business Requirement, FR = Functional Requirement, NFR = Non-Functional Requirement, INT = Integration Requirement, DR = Data Requirement, and any sub-prefixes (NFR-P = Performance, NFR-SEC = Security, etc.)
• Entity names from data models — Entity definitions, attribute names, data types, relationship terms
• Stakeholder role titles — Formal role names and their descriptions (e.g., SIRO, IAO, SRO)
• Architecture pattern names — Named patterns referenced in ADRs or strategy (e.g., CQRS, Event Sourcing, Microservices)
• Governance and compliance terms — Framework names, assessment criteria, maturity levels
• Financial and procurement terms — Investment terminology, procurement vehicle names (G-Cloud, DOS)

For each term, record:

1. Term — The word, phrase, or acronym
2. Definition — Clear, concise definition (inferred from artifact context)
3. Source — Which artifact(s) the term appears in (by Document ID)
4. Category — One of: Business, Technical, Governance, Financial, Data, Security, or domain-specific

4. Generate Glossary

Populate the template with extracted terms, organized alphabetically within categories. Each entry should:

• Provide a clear, jargon-free definition
• Reference the source artifact Document ID(s)
• Note the category for filtering
• Cross-reference related terms where applicable
• Flag any terms with inconsistent definitions across artifacts

Include a separate Acronyms table for quick reference.

5. Auto-Populate Document Control

Generate Document ID: ARC-{PROJECT_ID}-GLOS-v1.0 (for filename: ARC-{PROJECT_ID}-GLOS-v1.0.md)

• Set Document Type: "Project Glossary"
• Set owner, dates
• Review cycle: Quarterly (default for glossary documents)

6. Quality Check

Before writing the file, read .arckit/references/quality-checklist.md and verify all Common Checks pass. Fix any failures before proceeding.

7. Write the Glossary File

IMPORTANT: The glossary document can be a large document depending on the number of artifacts scanned. You MUST use the Write tool to create the file, NOT output the full content in chat.

Create the file at:

projects/{project-dir}/ARC-{PROJECT_ID}-GLOS-v1.0.md

Use the Write tool with the complete glossary content following the template structure.

8. Show Summary to User

After writing the file, show a concise summary (NOT the full document):

## Project Glossary Created

**Document**: `projects/{project-dir}/ARC-{PROJECT_ID}-GLOS-v1.0.md`
**Document ID**: ARC-{PROJECT_ID}-GLOS-v1.0

### Glossary Overview
- **Total Terms Defined**: [N]
- **Acronyms Catalogued**: [N]
- **Standards Referenced**: [N]
- **Source Artifacts Scanned**: [N]

### Terms by Category
- **Business**: [N] terms
- **Technical**: [N] terms
- **Governance**: [N] terms
- **Financial**: [N] terms
- **Data**: [N] terms
- **Security**: [N] terms

### Source Artifacts
- [List each artifact scanned with Document ID]

### Coverage Gaps
- [Note any missing artifacts that would add terminology]
- [Note any terms with ambiguous or missing definitions]
- [Note any inconsistencies found across artifacts]

### Next Steps
1. Review glossary with domain experts for accuracy
2. Validate acronym expansions with stakeholders
3. Add missing definitions for flagged terms
4. Review data model terminology: `$arckit-data-model`

**File location**: `projects/{project-dir}/ARC-{PROJECT_ID}-GLOS-v1.0.md`

---

CRITICAL - Auto-Populate Document Information Fields:

Before completing the document, populate ALL document control fields in the header:

Construct Document ID:

• Document ID: ARC-{PROJECT_ID}-GLOS-v{VERSION} (e.g., ARC-001-GLOS-v1.0)

Populate Required Fields:

Auto-populated fields (populate these automatically):

• [PROJECT_ID] -> Extract from project path (e.g., "001" from "projects/001-project-name")
• [VERSION] -> "1.0" (or increment if previous version exists)
• [DATE] / [YYYY-MM-DD] -> Current date in YYYY-MM-DD format
• [DOCUMENT_TYPE_NAME] -> "Project Glossary"
• ARC-[PROJECT_ID]-GLOS-v[VERSION] -> Construct using format above
• [COMMAND] -> "arckit.glossary"

User-provided fields (extract from project metadata or user input):

• [PROJECT_NAME] -> Full project name from project metadata or user input
• [OWNER_NAME_AND_ROLE] -> Document owner (prompt user if not in metadata)
• [CLASSIFICATION] -> Default to ${default_classification}; if unavailable, use "OFFICIAL" for UK Gov, "PUBLIC" otherwise (or prompt user)

Calculated fields:

• [YYYY-MM-DD] for Review Date -> Current date + 30 days

Pending fields (leave as [PENDING] until manually updated):

• [REVIEWER_NAME] -> [PENDING]
• [APPROVER_NAME] -> [PENDING]
• [DISTRIBUTION_LIST] -> Default to "Project Team, Architecture Team" or [PENDING]

Populate Revision History:

| 1.0 | {DATE} | ArcKit AI | Initial creation from `$arckit-glossary` command | [PENDING] | [PENDING] |

Populate Generation Metadata Footer:

The footer should be populated with:

**Generated by**: ArcKit `$arckit-glossary` command
**Generated on**: {DATE} {TIME} GMT
**ArcKit Version**: {ARCKIT_VERSION}
**Project**: {PROJECT_NAME} (Project {PROJECT_ID})
**AI Model**: [Use actual model name, e.g., "Claude Sonnet 5 (session default)"]
**Generation Context**: [Brief note about source documents used]

---

Output Instructions

CRITICAL - Token Efficiency:

• Write the full glossary to file using the Write tool
• DO NOT output the full document content in the response
• Show ONLY the summary section (Step 8) to the user
• The glossary can contain hundreds of terms — outputting it in chat wastes tokens

Important Notes

1. Extraction, Not Invention: This command extracts and consolidates terminology from existing artifacts. It should NOT invent new terms or definitions not grounded in the project artifacts. If a definition must be inferred, note it as "Inferred from context".

2. Use Write Tool: The glossary document can be large depending on the number of artifacts. ALWAYS use the Write tool to create it. Never output the full content in chat.

3. Consistency Checking: If the same term is defined differently across artifacts, flag the inconsistency and use the most authoritative source (typically the artifact that introduced the term).

4. Alphabetical Organization: Terms within each category must be sorted alphabetically for easy lookup.

5. Cross-References: Where terms are related (e.g., "SRO" relates to "Senior Responsible Owner"), include cross-references to help readers navigate.

6. Living Document: The glossary should be updated when new artifacts are created. Note this in the document's maintenance section.

7. Integration with Other Commands:

   • Glossary is informed by: $arckit-requirements, $arckit-data-model, $arckit-stakeholders, $arckit-principles, $arckit-sobc, $arckit-research, $arckit-adr, $arckit-strategy, $arckit-risk
   • Glossary feeds into: $arckit-data-model (validated entity/attribute names)

8. Version Management: If a glossary already exists (ARC--GLOS-v.md), create a new version (v2.0) rather than overwriting. Glossaries should be versioned to track terminology evolution.

9. Scope: If the user specifies "all projects", scan artifacts across all project directories and create a consolidated glossary in projects/000-global/.

• Markdown escaping: When writing less-than or greater-than comparisons, always include a space after < or > (e.g., < 3 seconds, > 99.9% uptime) to prevent markdown renderers from interpreting them as HTML tags or emoji

Suggested Next Steps

After completing this command, consider running:

• $arckit-data-model -- Review data model for entity/attribute terminology