From e96b002837245eb2124c3600386434685176a6da Mon Sep 17 00:00:00 2001 From: Karunanidhi Mishra <11963379+kmishra1204@users.noreply.github.com> Date: Sat, 4 Jul 2026 21:22:12 -0500 Subject: [PATCH] docs: add taxonomy term style guide --- README.md | 1 + docs/term-style-guide.md | 182 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 183 insertions(+) create mode 100644 docs/term-style-guide.md diff --git a/README.md b/README.md index 8d778c4..cfd8b4d 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,7 @@ All meeting recordings and AI summaries can be found on your [LFX Individual Das | [`landscape/`](landscape/) | Master landscape.yml configuration file for the AAIF Ecosystem Architecture Map | | [`taxonomy/`](taxonomy/) | Interactive shared taxonomy web dashboard explorer with Tri-Mode Architecture | | [`CONTRIBUTING.md`](CONTRIBUTING.md) | Contributor guidelines, pull request workflows, and review roles | +| [`docs/term-style-guide.md`](docs/term-style-guide.md) | Style guide for candidate terms, disambiguators, aliases, and definitions | diff --git a/docs/term-style-guide.md b/docs/term-style-guide.md new file mode 100644 index 0000000..757827a --- /dev/null +++ b/docs/term-style-guide.md @@ -0,0 +1,182 @@ +# Term Style Guide + +This guide explains how to draft candidate taxonomy terms, one-line disambiguators, and later full definitions for the AAIF Taxonomy and Landscape Workstream. + +Use it with: + +- `CONTRIBUTING.md` +- `docs/data-schemas.md` +- `taxonomy/taxonomy-data.js` + +## Purpose + +The taxonomy is a shared index across working groups. It should help readers understand how terms relate without erasing working-group-specific meaning. + +Good taxonomy writing is: + +- vendor-neutral +- pre-competitive +- clear enough for non-specialists +- precise enough for technical review +- careful about look-alike terms +- explicit when a term contrasts with another term + +## Candidate term checklist + +Before submitting a candidate term, check: + +- [ ] The term is relevant to at least two AAIF working groups or is foundational to the AAIF ecosystem. +- [ ] The term is written in sentence case. +- [ ] The term does not include vendor, product, or marketing language. +- [ ] The one-line disambiguator explains what makes the term different from nearby concepts. +- [ ] Similar existing terms were checked before proposing a new row. +- [ ] If the term is a synonym, it is proposed as an alias instead of a new concept. +- [ ] If the term is adjacent but distinct, the distinction is stated plainly. + +## Term formatting + +Use sentence case: + +- Good: `Agent behavior trace` +- Good: `Human approval checkpoint` +- Avoid: `Agent Behavior Trace` +- Avoid: `Enterprise-Grade Agent Observability` + +Capitalize proper nouns and acronyms: + +- `MCP server` +- `OpenTelemetry span` +- `W3C Trace Context` + +Avoid overloaded punctuation unless the punctuation is part of a known name. + +## One-line disambiguators + +Early collection asks for one short line per term. This is a disambiguator, not a full definition. + +Use this shape: + +```text +Term - one short line that says what makes this concept distinct. +``` + +Examples: + +```text +Agent behavior trace - an observable record of agent actions, decisions, tool use, and outcomes across a session or task. +Human approval checkpoint - a traceable point where execution pauses until a human approves, rejects, or escalates an action. +Tool invocation - a recorded agent request to an external capability, including intent, target, result, and side-effect class. +``` + +Keep the line short enough that it can fit in a whiteboard table and still be reviewed across working groups. + +## Full definition shape + +When a term moves from candidate collection into the repository taxonomy data, use this shape: + +1. Name the concept. +2. State what boundary it covers. +3. Explain what it is not, if confusion is likely. +4. Keep implementation examples out of the core definition. +5. Put historical or review context in `scopeNote`. + +Example pattern: + +```text +An agent behavior trace is a structured record of observable agent activity across a session, task, or workflow. It captures events such as tool invocation, delegation, approval, outcome, and side-effect metadata. It differs from an LLM-call trace, which records model invocation details rather than the higher-level behavior of an agent system. +``` + +## Aliases + +Use aliases for true synonyms, spelling variants, and historical names. + +Use an alias when: + +- the terms mean the same thing in the taxonomy context +- one term is a common abbreviation +- a term changed name but the concept did not change + +Do not use an alias when: + +- two working groups intentionally use similar terms differently +- one term is a subtype of the other +- the relationship is contrast rather than synonymy + +When in doubt, preserve both terms and ask for working-group review. + +## Related and contrasting terms + +Use `relatedTerms` for adjacent concepts that should be discoverable together. + +Use `contrastsWith` when two terms are commonly confused but represent different concepts. + +Examples: + +| Term | Contrast | Reason | +| --- | --- | --- | +| `Agentic workflow` | `Deterministic workflow` | One adapts through agent decisions; the other follows predefined control flow. | +| `Tool invocation` | `Protocol message` | One describes a capability request; the other describes a transport or protocol exchange. | +| `Approval checkpoint` | `Policy decision` | One is a human or workflow pause point; the other is a machine-evaluated decision result. | + +Definitions should state the distinction directly instead of relying only on metadata. + +## Scope notes + +Use `scopeNote` for: + +- working-group context +- review dates +- known boundary debates +- why a look-alike term was preserved +- links to relevant issues or pull requests + +Do not put the main definition only in `scopeNote`. The `definition` field should stand on its own. + +## Category selection + +Use the approved categories from `docs/data-schemas.md`. + +Choose the primary category by asking: + +- Is this mainly a risk or failure mode? Use `Agentic Threats`. +- Is this mainly about authentication, authorization, identity, or access? Use `Identity & Authorization`. +- Is this mainly about runtime, deployment, trace, workflow, or system structure? Use `Infrastructure & Architecture`. +- Is this mainly about what agents, tools, protocols, or interfaces can do? Use `Capabilities & Interfaces`. +- Is this mainly about oversight, policy, compliance, or process? Use `Governance & Compliance`. + +If more than one category seems plausible, choose the most useful navigation home and capture related concepts through `relatedTerms`, `contrastsWith`, or `workgroups`. + +## Workgroup attribution + +Use `workgroups` to show shared interest, not ownership by assertion. + +List a working group when: + +- the term affects that working group's deliverables +- the working group contributed or reviewed the term +- the term creates an explicit boundary with that working group's domain + +Do not list a working group only to increase visibility. + +## Writing anti-patterns + +Avoid: + +- marketing adjectives such as "best", "leading", "revolutionary", or "enterprise-grade" +- vendor-specific framing unless the term itself is a proper noun +- definitions that prescribe an implementation +- merging look-alike terms without working-group sign-off +- full technical essays in the one-line disambiguator field +- security, legal, or compliance claims without review from the relevant working group + +## Review questions + +Reviewers can use these questions: + +- Is the term scoped to a shared taxonomy rather than a single implementation? +- Would another working group understand the term without private context? +- Does the disambiguator distinguish the term from similar concepts? +- Are aliases true synonyms? +- Are related and contrasting terms explicit? +- Is the definition neutral and pre-competitive? +- Does the entry avoid vendor or product promotion?