Add a shared skill for reviewing ETSI standards.

---

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.

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.

## Workflow

```

Review progress:

- [ ] 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

```

**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

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.

**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.

## Report template

```markdown

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

## Summary

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

## Findings

### Major

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

   - Text: "<exact quote>"

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

   - Proposal: "<replacement text>"

### Minor

...

### Editorial

...

## Open questions for the committee

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

```

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.

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

## Example finding

```markdown

1. **Testability** — 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"

```

# Review checklist: Writing World Class Standards

Rules condensed from `assets/AGuideToWritingWorldClassStandards.pdf` (ETSI, 2020). For detailed

drafting and language rules see also `assets/ETSI-Drafting-Rules-v53.pdf`,

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

## Contents

- Qualities of a world class standard

- Deliverable types

- Requirement quality

- Provision verbs

- Language

- Context and conditions

- Combining requirements

- Testability

- Optional requirements and profiles

- Specialized notations

- Terms, symbols, abbreviations

- References

- Maintenance, compatibility, change requests

- Test specifications

## Qualities of a world class standard

- Well-defined objectives that respond to real needs.

- Complete and accurate: all requirements needed to achieve the objectives; only essential

  supporting information.

- Easy to understand and implement; readers who did not take part in the drafting must

  understand it without making assumptions.

- Clear distinction between normative (how to comply) and informative (helps understanding) text.

- Validated and maintained.

- Specifies *what* an implementation achieves, not *how*; leaves room for product

  differentiation; contains no implementation details or constraints.

## Deliverable types

| Type | Approved by | Content |

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

| TS | Responsible TC | Normative |

| ES | ETSI membership | Normative |

| EN (possibly Harmonised Standard) | TC, then National Standards Organizations | Normative |

| TR | Responsible TC | Informative |

| EG | ETSI membership | Informative |

| SR | Responsible TC | Informative |

| GS | Responsible ISG | Normative |

| GR | Responsible ISG | Informative |

Informative deliverables (TR, EG, SR, GR) shall not contain requirement wording.

## Requirement quality

Each requirement must be:

| Quality | Check |

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

| Necessary | Only what is needed for the objectives; no imposed implementation approach. |

| Unambiguous | Exactly one interpretation. |

| Complete | All information needed to understand it, directly or by reference. |

| Precise | Worded exactly; no unnecessary detail. |

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

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

## Provision verbs

| Provision | Positive | Negative | Forbidden alternatives |

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

| Requirement | shall | shall not | must, is required to, has to, will, is (present tense) |

| Recommendation | should | should not | ought to |

| Permission | may | need not | can, may not (ambiguous) |

- Present tense in normative text makes it unclear whether a requirement is meant:

  "the SPM requests a transport disconnection" becomes "the SPM shall request a transport

  disconnection".

- Requirement words (`shall`, `must`, `have to`, `required to`) are not permitted in

  informative text. If they seem needed, the text is probably not informative.

- The verbs apply inside optional features too.

## Language

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

  non-standard idiom.

- 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".

- Name the actor: "the bitstreams shall be aggregated" becomes "the multiplexer shall aggregate

  the bitstreams".

- Separate independent requirements; do not let a second sentence read like part of the first

  sentence's condition.

## Context and conditions

- **Static requirements** (independent of time or events) can appear in any order.

- **Dynamic requirements** (cause and effect) need careful ordering and composition.

- **Environmental context** (behaviour of peer entities specified elsewhere) uses non-normative

  wording: "the network will respond with ... / can respond with ...".

- **Descriptive context** helps understanding; removing it must not change the requirement.

- **Conditions**: preferably the condition comes first ("With the ME switched off ..., the

  voltages ... shall be ..."). The scope of a condition over several requirements must be

  explicit: "If COND1 is fulfilled then *both* REQ1 and REQ2 apply."

- A condition defined elsewhere must be easy to locate (cross-reference).

- **Alternatives**: state what happens if the condition is not met. Prefer two requirements

  with mutually exclusive conditions over "otherwise".

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

## Combining requirements

- Static requirements may be combined in any form ("dimensions of 15 cm x 20 cm x 10 cm

  (length x width x height respectively)").

- Dynamic order: "shall send a SETUP message and shall start timer T30" means any order;

  "... and then shall start timer T30" means sequence. Check which one is intended.

- "REQ1 and REQ2 or REQ3 but not REQ4" is ambiguous. Use `either`, `neither`, `both`,

  `at least`: "REQ1 and either REQ2 or REQ3".

## Testability

- Every requirement is testable at least in principle; testability implies observability.

  An unobservable requirement is questionable.

- An observable but imprecise requirement is not testable: "respond immediately" becomes

  "respond within 30 ms".

- Watch for: immediately, quickly, sufficient, appropriate, reasonable, normally, as far as

  possible, etc., and/or, user-friendly, efficient.

- Standardized testing only uses normative interfaces; requirements on internal behaviour that

  cannot be observed at an interface are suspicious.

## Optional requirements and profiles

- The number of options is minimized.

- For each option the standard states: under which conditions it applies, which other options

  become mandatory when it is implemented, and the consequences of omitting it.

- Options must preserve interoperability. If sending a message or field is optional, receiving

  it is mandatory.

- Optional features are introduced explicitly: "The following feature(s) may be supported."

- Many options call for profiles, which are standards that fix the option choices for a context.

## Specialized notations

- Only internationally standardized languages known in industry are used (ASN.1, XML, UML, SDL,

  MSC, TTCN-3), respecting their syntax and semantics. Verify with tools where possible.

- The standard states which notation parts are normative and which are informative.

- If text and notation are both normative, the standard states which takes precedence.

- Message structure and encoding are specified in ASN.1 or XML, not in plain text.

- Interactions use MSC or UML sequence diagrams; complex behaviour uses SDL or UML state charts.

- Diagrams are encouraged where text is hard to follow.

## Terms, symbols, abbreviations

- 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.**

- 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",

  "Asymmetric Digital Subscriber Line", "... Loop" and paraphrases.

- Meanings align with related standards and the industry (TEDDI, the vocabulary of the standard

  set).

## References

- All references are publicly available, normative references in particular.

- Normative references are only those cited in normative provisions. Informative references are

  cited for justification or clarification.

- References point to specific clauses, paragraphs, figures or tables.

- Undated references mean the latest edition; check that this is intended. Use a specific

  version when needed.

- Each listed reference is cited in the text, and each cited reference is listed.

## Maintenance, compatibility, change requests

- Compatibility with earlier versions and related standards is a primary objective; intended

  incompatibility is stated clearly.

- A change is reviewed in the context of the whole standard and directly related standards;

  consequent changes are planned together.

- A CR identifies the requester; the deliverable number, title and latest published version;

  the proposed change; and the reason.

- A CR is evaluated as necessary (fixes a defect), desirable (market-relevant extension or

  improvement) and feasible (technology, cost, timescale).

## Test specifications

- Correct use of shall/should/may lets tests be classified as mandatory or optional.

- Requirements are identifiable so that ICS/PICS, Test Purposes and TTCN-3 test suites can be

  derived from them.

- Conformance testing follows ISO/IEC 9646; interoperability testing follows EG 202 237.

../.agents/skills

 No newline at end of file