prometeu-studio/docs/pbs/agendas/11.2. Diagnostics Workshop 2 - Wording, Notes, and Help Surface.md

PBS Diagnostics Workshop 2

Status: Active

Purpose

Run the second focused discussion for 11. Diagnostics Specification.md on the human-facing surface:

• wording stability,
• required versus optional notes,
• help text,
• and the boundary between normative content and tooling freedom.

Why This Slice Second

This slice should follow Workshop 1 because wording cannot be scoped responsibly until the diagnostic identity and minimum attribution package are already settled.

Proposed Meeting Order

1. Reconfirm the identity and attribution baseline from Workshop 1.
2. Close which human-facing wording elements are normative.
3. Close whether notes and help text are ever required.
4. Close the illustrative versus normative example policy.
5. Record warning and backend mapping topics for later workshops.

Decisions To Produce

1. The normative boundary for human-facing wording.
2. Whether notes are mandatory for any diagnostic classes.
3. Whether help text is part of the v1 contract.
4. Whether example wording in the spec is illustrative or binding.

Candidate Decisions

1. Human Wording Is Illustrative Except For Distinguishing The Rejection Class

Candidate direction:

• wording does not need to be byte-for-byte stable across implementations,
• but it must remain specific enough to distinguish the rejection class,
• and it must not contradict the governing spec rule.

Rationale:

• This preserves tool freedom while keeping diagnostics usable.

2. Notes Are Optional By Default

Candidate direction:

• notes are optional quality features in v1,
• except where a later explicit rule may require related-location reporting for a narrow class.

Rationale:

• This keeps conformance small while leaving room for richer UX.

Alternative to discuss:

• require notes for multi-file conflicts because they are otherwise under-attributed.

3. Help Text Is Outside Core Conformance

Candidate direction:

• help text, suggestions, and remediation hints are encouraged,
• but not part of the normative minimum contract.

Rationale:

• This avoids binding the spec to one editorial style or educational approach.

4. Spec Examples Are Illustrative Unless Marked Normative

Candidate direction:

• sample messages in 11 are examples only,
• and the normative content lives in phase, attribution, and class requirements.

Rationale:

• This prevents examples from accidentally becoming the wording standard.

Questions To Resolve In The Room

1. Should any diagnostic class require notes by default in v1?
2. Is there any value in standardizing wording templates now?
3. Should the spec reserve words like error, note, and help as output categories?
4. Does conformance need to inspect wording classes at all?
5. How much editorial freedom is acceptable before diagnostics stop feeling stable?

Expected Outputs

This workshop should produce:

1. a decision record for wording stability,
2. a decision record for notes/help obligations,
3. editing guidance for future 11 examples,
4. and carry-forward items for conformance discussion in 13.

Explicit Deferrals For Workshop 3

• mandatory warnings,
• cost visibility taxonomy,
• and backend-originated failure mapping.

Inputs

• docs/pbs/specs/11. Diagnostics Specification.md
• docs/pbs/specs/13. Conformance Test Specification.md
• docs/pbs/agendas/11. Diagnostics Agenda.md
• docs/pbs/agendas/11.1. Diagnostics Workshop 1 - Diagnostic Identity and Attribution.md