Extend the ETSI review skill so long drafts stay reviewable.

---

name: reviewing-etsi-standards

description: Reviews ETSI standards, draft clauses and change requests against the rules of the ETSI guide "Writing World Class Standards" (requirement quality, shall/should/may, conditions, testability, options, references, terminology, Use of English, maintenance). Use when the user asks to review, check, proofread or assess an ETSI deliverable (ES, EN, TS, TR, EG, GS), a TTCN-3 standard clause, a draft in src/, or a change request.

description: Reviews ETSI standards, draft clauses and change requests against the ETSI guide "Writing World Class Standards" and the ETSI Drafting Rules. Checks that every requirement is necessary, unambiguous, complete, precise, consistent and testable, and finds ambiguous wording, misused or undefined technical terms, and semantic gaps. Handles long documents by delegating the term inventory, section reviews, cross-section checks, verification and report writing to subagents. Use when the user asks to review, check, proofread or assess an ETSI deliverable (ES, EN, TS, TR, EG, GS), a TTCN-3 standard clause, a draft in src/, or a change request.

disable-model-invocation: true

---

# Reviewing ETSI Standards

Source of the rules: `assets/AGuideToWritingWorldClassStandards.pdf`. The full checklist with

examples is in [reference.md](reference.md); read it before the first review in a session.

Files in this skill:

- [quality-checks.md](quality-checks.md): the six requirement qualities as questions, the

  ambiguity catalogue, the terminology check and the semantic gap analysis. This is the core

  of the review; read it before the first review in a session.

- [reference.md](reference.md): the remaining ETSI rules (deliverable types, provision verbs,

  language, conditions, options, notations, references, maintenance).

- [delegation.md](delegation.md): how to split a long review across subagents.

- [scripts/scan.sh](scripts/scan.sh): the mechanical search.

Sources: `assets/AGuideToWritingWorldClassStandards.pdf`, `assets/ETSI-Drafting-Rules-v53.pdf`,

`assets/ETSI-Use-of-English.pdf`, `assets/ETSI-Spelling-List.pdf`.

## Workflow

```

Review progress:

- [ ] 0. Size the text and choose a plan

- [ ] 1. Identify the document and its type

- [ ] 2. Check every requirement (normative text)

- [ ] 3. Check informative text, notes and examples

- [ ] 4. Check terms, abbreviations, references

- [ ] 5. Check language (British English, impersonal style)

- [ ] 6. Check maintenance aspects (if a revision or CR)

- [ ] 7. Write the report

- [ ] 2. Build the term inventory

- [ ] 3. Run the mechanical scan

- [ ] 4. Review each section: six qualities, informative text, language

- [ ] 5. Semantic gap analysis per feature

- [ ] 6. Cross-section consistency and terminology

- [ ] 7. Maintenance (if a revision or CR)

- [ ] 8. Write the report

```

**0. Size the text.** Count lines and list headings (`rg -n '^#{1,4} ' <file>`). For a PDF,

extract the text with `pdftotext -layout` and count pages.

- Up to about 300 lines: review inline in one pass, findings kept in the conversation.

- Longer: delegate. Read [delegation.md](delegation.md) now and follow it. The parent

  orchestrates and does not read the text; subagents build the term inventory, review the

  sections in parallel, check terminology and consistency, verify the Major findings, and

  write the report, all through files in `reviews/<name>/`.

- The summary states coverage: `Reviewed: … Not reviewed: …` (or `Not reviewed: none`).

**1. Identify the document.** Determine the deliverable type (TS, ES, EN, TR, EG, SR, GS, GR),

whether it is normative or informative, and what is under review: a full deliverable, a clause

(for example a file in `src/`), or a change request (for example a file in `docs/mantis/`).

Restrict the review to the text that was provided.

**2. Requirements.** For each normative sentence, check it is necessary, unambiguous, complete,

precise, consistent and testable (section "Requirement quality" in

reference.md). Pay particular attention to:

- the provision verbs: `shall`/`shall not`, `should`/`should not`, `may`/`need not`. Report

  `must`, `can` used as permission, `may not`, and requirements stated in the present tense

  (`is`, `requests`) or with `will`, `is required to`, `ought to`.

- passive voice that hides the actor ("the bitstreams shall be aggregated").

- the scope of conditions, the alternative when a condition does not hold, and ambiguous

  combinations of `and`/`or`.

- the order of dynamic requirements (`and` versus `and then`).

- vague, untestable terms (`immediately`, `fast`, `appropriate`, `etc.`).

- error and exceptional behaviour that is specified less precisely than normal behaviour.

- optional requirements: what conditions apply, what becomes mandatory, what the consequences

  of omission are, and whether the receiving side must support optional elements.

**3. Informative text.** Report `shall`, `must`, `have to` or `required to` in informative text,

notes, examples, and informative deliverables (TR, EG, SR, GR). Report tutorial or narrative

text that hides what is essential for compliance.

**4. Terms and references.** Each term used in requirements is defined; definitions contain no

requirements; each term, abbreviation and symbol is used consistently (no switching between the

full term, the abbreviation and paraphrases). References are publicly available and point to

specific clauses, tables or figures. Undated references are deliberate.

**5. Language.** British English spelling, no first or second person (`I`, `we`, `you`), no

third person personal pronouns (`he`, `she`, `they`), no idiom, consistent style across

contributions.

**6. Maintenance (revisions and CRs).** Check compatibility with earlier versions and related

Review only the text that was provided.

Look outside that text only to check a term, abbreviation, cross-reference, or sibling rule

that the text relies on. Search for it and read the matching definition or passage. Do not

read whole files outside the review. A lookup that needs more than two or three searches goes

to a lookup subagent (brief in delegation.md), which returns only the answer and citations.

**2. Term inventory.** Follow step 1 of "Terminology check" in quality-checks.md: defined

terms, inline definitions, and the technical terms the requirements rely on, each with its

definition and location. In this repository the terms clause is

`src/03-terms-and-references.md`. For long texts write the inventory to

`reviews/<name>/terms.md` before any section is reviewed, so that every reviewer judges

term usage against the same list.

**3. Mechanical scan.** Run `scripts/scan.sh <file>...` (`-c` for counts only, `-r FROM:TO`

for one section). It searches

prose only (Markdown code is blanked; line numbers match the file) for wrong provision verbs,

vague words, open lists, `and`/`or` and condition words, quantifiers, unclear antecedents,

double negation, statements of belief, gap markers, personal pronouns, contractions, and

spelling (American spelling and `-ise` where ETSI uses `-ize`). A hit is a candidate, not a

finding: read the sentence, and skip hits in examples and informative text unless the rule

concerns them. Present-tense requirements (`is`, `are`) are too common to search for; judge

them while reading.

**4. Review each section.** Read the section once and apply all sentence-level checks in that

read; do not make a separate pass per rule.

- For each normative statement, ask the six questions in "The six tests" of

  quality-checks.md (necessary, unambiguous, complete, precise, consistent, testable) and run

  the ambiguity catalogue on it. For each requirement, sketch a positive and a negative test

  in one line; if neither can be sketched, the requirement is untestable.

- Provision verbs: `shall`/`shall not`, `should`/`should not`, `may`/`need not`. Report

  `must`, `can` used as permission, `may not`, `is to`, and requirements in the present tense

  or with `will`.

- Conditions, alternatives, `and`/`or` combinations, and the order of dynamic requirements

  (`and` versus `and then`): see "Context and conditions" and "Combining requirements" in

  reference.md.

- Error and exceptional behaviour is specified as precisely as normal behaviour.

- Optional requirements: conditions, what becomes mandatory, consequences of omission, and

  whether the receiving side must support optional elements.

- Informative text: report `shall`, `must`, `have to` or `required to` in notes, examples

  and informative deliverables (TR, EG, SR, GR), and narrative text that hides what is

  essential for compliance. An example comment that only repeats a normative requirement is

  Editorial. A note, example or comment that is the only statement of a requirement is Major.

- Examples: check that each example is valid under the rules and that its comments state the

  result the rules give.

- Language: British English with ETSI `-ize` spelling, no first or second person, no

  personal pronouns for people, no contractions, no idiom. Use the scan hits as the list.

- Every term use is checked against the inventory (step 3 of "Terminology check").

**5. Semantic gap analysis.** For each feature, rule or construct the section specifies, run

"Semantic gap analysis" in quality-checks.md: list the dimensions, build a small case table,

cite the sentence that covers each case, and probe the boundary cases. Report each gap with a

minimal concrete case and the readings an implementer could choose. Where the intent is not

evident from the standard, put the gap under "Open questions for the committee" instead of

inventing a proposal.

**6. Cross-section consistency and terminology.** After all sections:

- Definitions: substitution test, circularity, requirements in definitions, agreement with

  use (steps 2 and 4 of "Terminology check").

- Confusable pairs (step 5): report pairs that are used as synonyms anywhere in the text.

- Consistency: compare every statement about the same concept (the ledger files for long texts),

  analogous constructs, the grammar, tables and examples (section "Consistent").

- References: publicly available, specific clauses, tables or figures; undated references

  deliberate; each listed reference cited and each cited reference listed.

**7. Maintenance (revisions and CRs).** Check compatibility with earlier versions and related

standards, and that a CR identifies the requester, the deliverable number, title and version,

the proposed change, and the reason. Assess whether the change is necessary, desirable and

feasible.

feasible. Review the changed text in the context of the clauses it affects.

**8. Report.** Use the template below. Quote the original text exactly, cite its location

(`file:line` for Markdown, page and clause for a PDF), and give concrete replacement text

wherever the intent is evident. Do not edit the document unless the user asks for it.

- The same problem in several places is one finding. List every location.

- Editorial findings go in a table (location, quote, proposal). If one pattern occurs more

  than about ten times, give the count, the pattern, and three examples.

- More than about 20 findings, or a long text: write the full report to

  `reviews/<name>/report.md` (`reviews/<name>.md` for a single short text) and put the

  summary in the chat.

## Long texts

**7. Report.** Use the template below. Quote the original text exactly, cite its location, and

give concrete replacement text wherever possible. Do not edit the document unless the user

asks for it.

Consistency, terminology and gaps span sections, but no single context window holds a long

text with all its findings. [delegation.md](delegation.md) assigns the steps above to

subagents (term inventory; section reviewers in parallel; terminology checker; consistency

checker; verifier; report writer), defines the files they exchange in `reviews/<name>/`,

and gives a self-contained brief for each. Each subagent returns a short summary; the

findings stay in files.

## Report template

# Review of <document id / clause> (<deliverable type>)

## Summary

Reviewed: <clauses or line ranges>. Not reviewed: <none, or what was left out>.

<2–4 sentences: overall quality, the most important problems, recommendation.>

| Quality | Major | Minor |

|---------|-------|-------|

| Necessary | n | n |

| Unambiguous | n | n |

| Complete (including semantic gaps) | n | n |

| Precise (including terminology) | n | n |

| Consistent | n | n |

| Testable | n | n |

## Findings

### Major

1. **<Rule category>** — <location (clause, line, table)>

1. **<Quality>: <defect>** — <file:line, or page and clause>

   - Text: "<exact quote>"

   - Problem: <why it breaks the rule; which reading is ambiguous>

   - Problem: <why it breaks the rule; the readings, or the uncovered case>

   - Proposal: "<replacement text>"

### Minor

...

### Editorial

...

| Location | Text | Proposal |

|----------|------|----------|

## Open questions for the committee

- <points where intent is unclear and the reviewer cannot propose a fix>

- <gap or ambiguity where the intent is unclear: the case, and the options>

```

`<Quality>` is one of the six qualities. Findings outside them use `Language`, `References`,

`Structure` or `Maintenance`.

Severity levels:

- **Major**: an ambiguous, contradictory, untestable or missing requirement, wrong provision

  verb, or a requirement in informative text. Any of these can lead to non-interoperable or

  non-conformant implementations.

- **Minor**: unclear conditions with an evident intended reading, inconsistent terminology,

  imprecise references.

- **Major**: an ambiguous, contradictory, untestable or missing requirement; a semantic gap

  where two conforming implementations can behave differently; a term misused so that a

  requirement changes meaning; a wrong provision verb; a requirement only in informative text.

- **Minor**: unclear conditions, gaps or terms with an evident intended reading; inconsistent

  terminology; imprecise references; unnecessary or duplicated requirements.

- **Editorial**: spelling, British English, style.

## Example finding

## Example findings

```markdown

1. **Testability** — clause 7.3, second paragraph

1. **Testable: unmeasurable criterion** — clause 7.3, second paragraph

   - Text: "it shall respond immediately with a SERVICE_ACK message"

   - Problem: "immediately" is not measurable; no test verdict can be derived.

   - Proposal: "it shall respond with a SERVICE_ACK message within 30 ms"

2. **Complete: semantic gap** — src/19.1-assignments.md:13

   - Text: "An assignment statement evaluates the expression on the right hand side and

     copies the result to the destination specified by the left hand side."

   - Problem: the order of evaluating the left and right hand sides is not specified. In

     `a[f()] := g();`, where `f` and `g` both change the same component variable, tools

     that evaluate `f()` first and tools that evaluate `g()` first assign to different

     elements or assign different values.

   - Proposal: open question: shall the left hand side be evaluated before the right hand

     side, after it, or is the order implementation-dependent?

```

# Delegating a review to subagents

A long review does not fit in one context window: the text, the scan hits, the lookups and

the findings together crowd out the attention needed for each sentence. The parent agent

therefore orchestrates and does not review. Subagents do the reading, exchange results

through files in `reviews/<name>/`, and return short summaries.

## Contents

- When to delegate

- Rules for the parent

- Working files

- Roles and order

- Briefs

## When to delegate

| Text | Plan |

|------|------|

| Up to about 300 lines | No subagents. Review inline. Use a lookup subagent only for a lookup that needs more than two or three searches. |

| About 300 to 1 500 lines | Delegate every role below. Section reviewers run in parallel. |

| More than 1 500 lines, or several files | As above, in batches of at most 4 section reviewers at a time. Split the term inventory by file if the terms clauses are long. |

## Rules for the parent

- Read only: the heading list, line counts, the summaries the subagents return, and the

  Summary section of `report.md`. Do not read the reviewed text, the scan output, the

  findings files or the ledger files. If a summary raises a question, ask the subagent

  again (resume it) or start a lookup subagent.

- Each brief is self-contained. Subagents do not see the conversation: give the document id

  and type, the exact files and line ranges, the skill path, the output files, and the

  return format. Use the briefs below and fill in every `<...>`.

- Subagents return at most about 15 lines: the files written, counts by severity, coverage,

  and open questions. They never return findings text; findings live in files.

- Run independent subagents in parallel (several subagent calls in one message). Wait for a

  phase to finish before starting the next phase that reads its files.

- Subagents that write files need a general-purpose subagent type with write access. A

  read-only explorer type is sufficient for lookups.

- Check every return for coverage. Review again any range reported as not reviewed, or list

  it under `Not reviewed` in the report.

## Working files

All in `reviews/<name>/`. Each file has one writer, so parallel subagents never write to the

same file.

| File | Writer | Content |

|------|--------|---------|

| `plan.md` | parent | document id and type, sections with file and line ranges, status of each role |

| `terms.md` | term inventory | term, definition, location; one line per term |

| `findings-<section>.md` | section reviewer | findings in the report format, written as they are found |

| `ledger-<section>.md` | section reviewer | `concept — claim — file:line`, one line per statement that defines or constrains a concept; then `new term — file:line` for terms not in `terms.md` |

| `findings-terminology.md` | terminology checker | definition and term-use findings across sections |

| `findings-consistency.md` | consistency checker | contradictions and unexplained differences across sections |

| `verification.md` | verifier | per Major finding: `confirmed`, `changed` (with the correction) or `rejected` (with the reason) |

| `report.md` | report writer | the merged report |

## Roles and order

1. **Parent**: steps 0 and 1 of SKILL.md. Choose sections (a top-level clause, or about 300

   lines, cut at headings). Write `plan.md`.

2. **Term inventory** (one subagent): step 2. Must finish before phase 3.

3. **Section reviewers** (one per section, parallel): steps 3, 4 and 5 for their section.

4. **Terminology checker** and **consistency checker** (parallel): step 6, from `terms.md`

   and the ledgers, with bounded lookups into the text.

5. **Verifier** (one subagent, or one per findings file for many Major findings): rereads the

   cited text of every Major finding and confirms it independently.

6. **Report writer** (one subagent): step 8, from all findings files and `verification.md`.

7. **Parent**: step 7 if the text is a revision or CR (delegate it like a section review if

   the affected clauses are long). Read the report Summary, check coverage, and give the

   user the summary and the report path.

## Briefs

Common header for every brief:

```text

You are part of a review of <document id> (<deliverable type>, normative|informative)

against the ETSI quality rules. Skill: .agents/skills/reviewing-etsi-standards

(SKILL.md, quality-checks.md, reference.md, scripts/scan.sh). Working directory:

reviews/<name>/. Do not edit the reviewed document. Quote text exactly and cite file:line.

Return at most 15 lines; never return the findings themselves.

```

### Term inventory

```text

<common header>

Task: step 2 of SKILL.md ("Terminology check", step 1, in quality-checks.md).

Sources: <terms clause file>, plus inline definitions in <files and line ranges>.

Write reviews/<name>/terms.md: one line per term: `term — definition — file:line`.

Mark empty definitions and definitions that contain requirements with `(!)`.

Return: number of terms, number marked (!), and the file path.

```

### Section reviewer

```text

<common header>

Task: steps 3, 4 and 5 of SKILL.md for <file> lines <from>-<to> (<clause title>) only.

Read quality-checks.md in full and the parts of reference.md that apply.

Run `scripts/scan.sh -r <from>:<to> <file>` for the scan hits of this section.

Judge term usage against reviews/<name>/terms.md; do not edit it.

Read other text only for bounded lookups (a definition, a cited clause, a sibling rule).

Write findings to reviews/<name>/findings-<section>.md as you find them.

Write reviews/<name>/ledger-<section>.md: every statement in the section that defines or

constrains a concept, then the technical terms you met that are not in terms.md.

Return: findings by severity, lines reviewed and not reviewed, open questions (one line each).

```

### Terminology checker

```text

<common header>

Task: step 6 of SKILL.md, terminology only ("Terminology check", steps 2, 4 and 5, in

quality-checks.md). Inputs: reviews/<name>/terms.md and the "new term" lines of

reviews/<name>/ledger-*.md. Search the reviewed text (<files>) for each term and its

confusable pairs; read only the matching lines and their paragraph.

Skip problems already reported in reviews/<name>/findings-*.md (search them by term).

Write reviews/<name>/findings-terminology.md.

Return: findings by severity and the file path.

```

### Consistency checker

```text

<common header>

Task: step 6 of SKILL.md, consistency only (section "Consistent" in quality-checks.md).

Inputs: reviews/<name>/ledger-*.md. Group the lines by concept and compare the claims.

Compare analogous constructs (siblings) across sections. Read the cited lines to confirm a

contradiction before reporting it.

Write reviews/<name>/findings-consistency.md.

Return: findings by severity and the file path.

```

### Verifier

```text

<common header>

Task: verify every Major finding in reviews/<name>/findings-*.md without trusting it.

For each one: check that the quote is exact and at the cited location; reread the

paragraph and any cited definition; decide whether the problem is real, whether the

severity is right, and whether the proposal is correct and does not break other text.

Write reviews/<name>/verification.md: `<file>#<number> — confirmed|changed|rejected — reason`.

Return: counts of confirmed, changed and rejected.

```

### Report writer

```text

<common header>

Task: step 8 of SKILL.md. Inputs: reviews/<name>/plan.md, reviews/<name>/findings-*.md,

reviews/<name>/verification.md. Drop rejected findings and apply the changes.

Merge findings that describe the same problem into one with all locations. Order Major

findings by impact. Fill in the quality table and the coverage line from plan.md and the

section returns: <coverage per section>.

Write reviews/<name>/report.md using the report template in SKILL.md.

Return: the Summary section of the report, and the file path.

```

### Lookup

```text

Answer one question about <document or repository path> and return only the answer with

file:line citations, at most 10 lines: <question, for example "Where is 'addressable value'

defined, and what does the definition say?">

```

| Consistent | No contradiction within the standard or with related standards. |

| Testable | A clear means of demonstrating compliance exists. |

The questions, patterns and procedures for checking each quality are in

[quality-checks.md](quality-checks.md).

## Provision verbs

| Provision | Positive | Negative | Forbidden alternatives |

- British English, consistent across all contributions; no spelling or grammatical errors; no

  non-standard idiom.

- ETSI spelling uses `-ize` for verbs such as initialize, organize, parameterize, recognize

  and serialize, but `-yse` in analyse and catalyse (`assets/ETSI-Spelling-List.pdf`).

  Exception: Harmonised Standard. Otherwise British spelling: behaviour, colour, centre,

  modelling, signalling, labelled, cancelled, fulfil, towards.

- No contractions (`isn't`, `can't`, `it's`). Only one negation per sentence.

- Impersonal: no `I`, `we`, `you`, `he`, `she`, `they`.

  Bad: "you should set the audio level to 0dB", "we recommend that it should not exceed

  100μA". Good: "the potential shall be set to +5 volts".

- All terms used in requirements are defined, especially specialized ones.

- Definition format: `term: definition` (for example "interface: common boundary between two

  associated systems"). **Definitions contain no requirements.**

- Drafting Rules, clause 2.11.1: definitions are in alphabetical order; a definition can

  replace the term in context; additional information is given only in notes or examples,

  numbered if there are several.

- All symbols are listed with a brief explanation; all abbreviations are listed with the full

  term.

- Once defined, the term or its abbreviation is used always and consistently. Do not mix "ADSL",