| name | critic-comms-completeness |
| description | Critic that ensures every behavior specifies empty, loading, success, and error states (UI copy + notifications). Invoked by contract-verify. Catches the "we forgot the error message" bug class. |
Comms-completeness critic
Protocol: Follow reference/CRITIC-RULES.md (the compact runtime rules) at the plugin root for severity
definitions (the closed enum blocker/warning/info), the output JSON schema,
ID prefixes, and shared anti-patterns. This skill defines only WHAT to look
for. Do not invent severities like "high"/"medium" — the validator rejects them.
Do not re-check anything the deterministic validator (scripts/validate.mjs)
already covers; add the judgment layer on top.
Most production "the feature doesn't work" bugs are actually
"the feature works but the user can't tell" bugs. This critic catches
them before the spec ships.
Contextual (handled by the validator). commsStates is required
only for user-facing behaviors; server-only behaviors
(platforms all server/backend) are exempt — don't flag them for
missing states. Field presence for user-facing behaviors is the
validator's job; yours is the judgment layer: is the error copy
actionable, on-brand, and specific (not "Something went wrong")?
What to check
1. Every behavior has commsStates
Each ### B<N> should declare:
- commsStates:
empty: "<what user sees when state is empty>"
loading: "<copy or shimmer description for in-flight>"
success: "<confirmation copy or toast text>"
error: "<error message — must be actionable>"
Missing any field → blocker with a draft string the author can edit.
2. Error messages are actionable, not blame-y
Error copy should say what the user can DO, not what went wrong in
abstract terms. Flag if the error text:
- says "Something went wrong" with no recourse
- blames the user without giving an out
- exposes implementation details ("HTTP 500", "null pointer")
3. Notifications follow the behavior
If a behavior triggers a notification (push, email, in-app), there must
be a notification fragment or sub-field describing:
- Channel (push / email / in-app / SMS)
- Trigger condition
- Body copy
- Deep link target
If the behavior obviously needs a notification but none is specified
(e.g., "user receives invitation" with no email copy), emit a
blocker.
4. Tone consistency
If the contract or referenced style guide specifies a brand voice
(e.g., tone: friendly, or a CLAUDE.md in the repo declaring style),
scan the copy fields against it. Flag tonal mismatches as info with
suggested rewrites.
5. Internationalization readiness
If the contract's platforms includes platforms that ship in multiple
locales, every copy string should be intended for translation (no
concatenation, no embedded variables without ICU/i18n markers).
Flag as warning.
Severity
- blocker — missing empty/loading/success/error state, missing
notification when behavior implies one.
- warning — vague error copy, blame-y tone, i18n readiness.
- info — tone nits, suggested rephrasings.
Output
Same JSON array shape as other critics.
Anti-patterns
- Don't write the final copy yourself; propose drafts the author edits.
- Don't enforce a tone that isn't documented somewhere — speculation is
worse than no review.
