Proactive shape detection, existing-bot audit, and verified Rich Message spec

[hlibsuslov]

Re-verified the whole skill against core.telegram.org on 2026-08-05. Bot API 10.2 (14 Jul 2026) is still the newest release — nothing was missed version-wise, but several documented facts were wrong or absent.

1. Corrected Rich Message spec (was inferred, not read)

The flagship table capability was documented from a guess marked (verify). It was wrong in three ways and would have produced non-working tables:

Documented before	Actually
rows: [{cells: […]}]	cells: is an Array of Array of RichBlockTableCell — no rows field, no row object
cell = {blocks:[{type:"paragraph",…}]}	cell = RichBlockTableCell {text, is_header, colspan, rowspan, align, valign}; text is RichText, which may be a plain String
Rich HTML with <thead>/<tbody>	those tags are not supported; <tr> goes directly inside <table>
—	is_bordered, is_striped, caption were missing

Also corrected:

• There is no InputRichBlockTableCell class — input tables reuse RichBlockTableCell.
• Omitting a cell's text renders an invisible cell (how you fill a rowspan/colspan hole).
• Type discriminators are not the class names: heading, pre, blockquote, pullquote, mathematical_expression, voice_note.
• InputRichMessage also carries is_rtl and skip_entity_detection.
• Rich HTML supports nine more named entities than regular HTML.
• Table cells accept inline formatting only.
• sendRichMessageDraft is private chats only and supports no direct file upload.

2. Limits promoted from "unverified" to documented

Four limits sat in a "third-party, not confirmed" section. They are officially documented under Rich Message Limits: 500 blocks, 16 nesting levels, 50 media, 20 columns.

The one that bites: table rows count toward the 500-block budget, so a long table exhausts it far sooner than the 32,768-character limit suggests.

3. New: proactive shape detection

references/content-shape-detection.md — the skill no longer waits to be asked to format something.

• Two-axis test: can you name the rows and the columns, with most intersections filled? Three yeses → table; one axis → list.
• Act / offer / ask protocol: act silently when already authoring that text; offer (naming message, shape, and reader gain) when the text was out of scope; ask only when the meaning would change.
• Explicit guard against over-formatting — a one-line Saved ✅ stays one line.

4. New: existing-bot audit and rework pipeline

references/auditing-existing-bots.md — most real work is not greenfield.

Scope → text inventory → five-axis diagnosis (shape / clarity / consistency / safety / localization) → findings tiered bugs → UX → polish → proposals grouped into a few ranked decisions, not sixty questions.

For "rework all the texts": agree the voice on 2–3 samples before bulk rewriting — otherwise the pass meant to remove inconsistency creates it. Works on a pasted snippet without demanding the whole repo.

5. New: Ephemeral Messages (Bot API 10.2)

references/ephemeral-messages.md — a UI surface the skill had missed entirely: private replies to one group member, the 15-second reply window, callback_query_id, the admin exception, and the explicit delivery-is-not-guaranteed contract (so nothing load-bearing may live there alone).

6. Security

Documented skip_entity_detection as a real injection surface: Telegram auto-detects @mentions, /commands, and phone-shaped strings in rich message bodies by default, turning untrusted text into live entities.

---

Activation description gained audit triggers (including Russian: «проанализируй бота», «переработай тексты»); evals gained 12 scenarios covering audit mode and detection calibration.

validate_skill.py and validate_references.py both pass with 0 warnings (SKILL.md was trimmed back under the 20,000-char progressive-disclosure threshold).

[Copilot]

Pull request overview

This PR updates the telegram-bot-ui skill documentation to reflect Bot API 10.2 (verified 2026-08-05), corrects previously inferred Rich Message/table specs and limits, and expands the skill’s workflow to proactively detect content “shape” and to support auditing/reworking existing bots.

Changes:

• Corrected and expanded Rich Message/table specifications, limits, and safety notes based on re-verification against official docs.
• Added proactive content-shape detection guidance (act/offer/ask protocol) and an audit pipeline for existing bots.
• Documented Ephemeral Messages (Bot API 10.2) and integrated it into the UI capability/change guidance.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
SKILL.md	Updates activation scope and core workflow to include proactive shape detection and audit mode.
README.md	Aligns public-facing description with the new audit + proactive detection positioning and re-verification notes.
evals/activation-evals.md	Adds activation/eval scenarios for audit mode and proactive formatting calibration.
references/ui-changelog.md	Expands the Ephemeral Messages entry with key constraints (time window, delivery caveat).
references/telegram-capabilities.md	Updates verification date and adds clarified Rich Message fields/limits/type discriminator details.
references/tables.md	Rewrites table guidance to match verified object shapes and Rich HTML/Rich Markdown constraints.
references/streaming-and-editing.md	Clarifies sendRichMessageDraft constraints (private chats only, no direct upload, draft semantics).
references/security-and-escaping.md	Documents rich-only named HTML entities and automatic entity detection risk + mitigation.
references/official-sources.md	Updates verification timestamps and adds direct source links for newly verified Rich Message objects/limits.
references/limits-and-splitting.md	Promotes Rich Message limits to “official” and adds broadcast-rate notes.
references/format-selection.md	Adds guidance to run shape detection before choosing the rendering mechanism.
references/ephemeral-messages.md	New: documents Ephemeral Messages/Commands surface, constraints, and UX rules.
references/content-shape-detection.md	New: defines the proactive detection rubric and act/offer/ask protocol.
references/auditing-existing-bots.md	New: defines the audit → diagnose → propose → rework pipeline for existing bots.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.