Review Process
How a new capability id gets proposed, checked, reviewed, and released.
Status: Draft. Not ratified yet. Questions go to the taxonomy owner (see Ownership).
Follow this process to add, change, or retire a capability id in the Capability Taxonomy.
How a new id gets in: a walkthrough
Story: a provider wants to register a soil testing agent. The id urn:capability:agriculture:soil:nutrient_analysis does not exist yet.
Step 0. Check first. The provider (or we, on their behalf) calls GET /capabilities and searches the tree and aliases. Nothing fits.
Step 1. Open a PR. The PR adds the new node to the taxonomy file. If the parent agriculture:soil does not exist either, the same PR adds it.
Step 2. CI runs the hard checks. These block the merge. No AI involved.
Step 3. The AI advisor posts one comment.(Future Scope) It never blocks anything.
Step 4. Humans decide. Two core-team approvals, then merge.
Step 5. Release. The node ships in the next taxonomy release and the Registry loads it.
Fast track. If the provider cannot wait for full review: one approver plus green CI lands the node as pending. The provider registers immediately. Full review later promotes it to active or retires it.
The CI checks (blocking, deterministic, no AI)
| # | Check | Example that fails | Why it fails |
|---|---|---|---|
| 1 | Format lint | urn:capability:Agriculture:CropHealth:x | uppercase letters |
| 2 | Parent must exist | adding ...:soil:nutrient_analysis when ...:soil is missing | orphan node |
| 3 | No duplicate id, no alias clash | adding disease_detection as a new node | it is already an alias of disease_diagnosis |
| 4 | Real description | “Nutrient analysis: analyses nutrients.” | restates the name, says nothing |
| 5 | Two examples minimum | node with an empty examples array | reviewers and seekers need them |
| 6 | No deletion | a PR that removes pest_id | deprecate instead, ids live forever |
| 7 | Complete deprecation | deprecated node without sunset or replacement | it would linger forever |
| 8 | Golden set passes | a rename that breaks a known-good discovery query | catches silent drift |
These rules live in code because code does not hallucinate and runs free on every PR.
The AI advisor (advisory only, never a gate)(Future Scope)
Runs after CI is green. It reads the full compiled taxonomy plus the diff, and posts one comment covering: possible overlap with existing nodes, parent placement, description quality, and naming consistency with sibling nodes.
Example comment it would post on our soil PR:
Advisory review (not a gate)
- Possible overlap. Proposed
agriculture:soil:nutrient_analysisvs existingagriculture:crop_health:soil_advisory. Evidence: both descriptions mention “soil nutrient recommendations”. If the new node is lab-style measurement and the old one is advice, keep both and sharpen both descriptions. If they are the same work, use an alias instead.- Parent placement.
agriculture:soilfits.agriculture:crop_healthwould be wrong: soil testing is not tied to a crop.- Description. Add the output (“returns nutrient levels and deficiency flags”). Right now only the input is described.
New anti-pattern learned: none this time.
The advisor must show evidence for every flag, like the quoted description overlap above. A verdict without evidence is noise.
The learning loop. When the advisor finds a new kind of mistake that a regex could catch, we write it down. A human approves the new rule, and it moves into the CI checks. Over time the free deterministic layer grows and the advisor stays focused on judgment calls. This loop is copied from OCSF.
Human review rules (the real gate)
- Two core-team approvals for a new id. One approval is enough for alias-only changes, description edits, and the pending fast track.
- The PR author never merges their own PR. Branch protection enforces this, not discipline.
- The deciding reviewer writes one line in the PR: what they checked, and whether they agreed with or overrode the advisor.
- Treat the advisor like a sharp junior reviewer. Often useful, sometimes wrong. Read its evidence, not its verdict, and check the flags yourself.
Reviewer quick guide
The seven questions to answer before approving:
- Is it really new? Search the tree and the aliases. Same meaning, different words: alias. Different work: new node.
- Right parent? A node sits under the most specific parent that is always true for it. Soil testing under
agriculture:soil, not underagriculture:crop_health. - Good name? A task-shaped noun phrase. Lowercase. No brand names, no tech names.
nutrient_analysisyes,gpt_soil_botno. - Real description? One sentence for input, one for output. Two examples minimum.
- Deprecating something? Replacement pointer plus sunset date, 90 days minimum.
- Deleting something? Never. Retire it instead.
- Did you write your one-line rationale? Including whether you overrode the advisor.
Ownership
The taxonomy has one named core-team owner. Changes land by PR plus core-team review. If a SIG forms, ownership moves to it.