Skip to content

docs: tighten webex comments - #37327

Merged
iamwhatever merged 1 commit into
mainfrom
crew/testoptimizer/src-quality-webex
Nov 14, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
crew/testoptimizer/src-quality-webex

Conversation

@iamwhatever

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Make the webex comments short, plain and true, so a reader (person or AI agent) gets each rule and its reason in fewer words.

Several comments in src/kiro_crew/webex/ take six to seventeen lines for one or two facts. This PR rewrites those comments. It changes no code.

Why it matters

Agents editing the Webex channel read these comments to learn why a budget, a separate message or a named alias set exists. A shorter comment with the same reason is easier to act on and to keep true.

Not a goal

  • No code change: the AST of every changed file is identical (proof below).
  • No docstring is touched.
  • No new comments that restate code.
  • transport_dispatch.py is skipped (open PR feat(redaction): scrub every persisted conversation row #36640 edits it).
  • The security notes are left as they are: tool-label sanitizing, approval nonces, accepted approval words, Device Manager host pinning, quarantine states and attachment-name redaction.

What changed (motivation → approach → change)

Comments only, in five files: commands.py, renderer.py, client.py, transport_dispatch_commands.py, transport_dispatch_origin.py (44 lines added, 60 removed). Each rewrite keeps the same facts and the reason.

Where Kind of fix
commands.py _ALIAS_TO_COMMAND wordy and hard to follow: the two test readers are now a two-item list
renderer.py edit budget, chunking, card message, redaction notice wordy
client.py scan retry budget wordy
transport_dispatch_commands.py dashboard TTL, transport_dispatch_origin.py drain name wordy

Examples:

  1. commands.py, _ALIAS_TO_COMMAND (17 lines, hard to follow)

    Before (second paragraph):

    #: The aliases stay as the named sets above rather than being spelled inline here,
    #: and ``_STOP_ALIASES`` MUST keep that name: a cross-channel tripwire ``getattr``s
    #: it off this module to check the shared cancel-during-a-governance-deny exemption
    #: covers every spelling this channel accepts. Inlining it costs nothing visible —
    #: the probe falls back to its default, and these two spellings are a subset of what
    #: the other channels contribute, so the union it asserts on does not move. The
    #: coverage just stops. The rest have a reader outside this module too: ...
    

    After:

    #: Keep the aliases as the named sets above, not inline here. Tests read them by
    #: name and fall back silently when one is missing, so inlining keeps them green
    #: while the coverage stops:
    #:
    #: * ``_STOP_ALIASES`` is ``getattr``-ed by a cross-channel tripwire that checks
    #:   the cancel-during-a-governance-deny exemption covers every stop spelling.
    #: * every ``*_ALIASES`` frozenset is collected by the quick-prompt
    #:   reserved-token test, so a Webex-only spelling added later is checked.
    
  2. renderer.py, edit budget

    Before:

    # Webex allows 10 edits per message. Split that budget ONCE, here, so the
    # arithmetic is readable rather than implied by a single constant: status frames
    # get the first slice and the rest is held back for the final answer. A status
    # frame that FAILS burns the whole remaining status budget (an edit-cap or
    # rate-limit 400 means further status edits will fail too), so the final edit
    # can never race the cap.
    

    After:

    # Webex allows 10 edits per message, split here: status frames get the first
    # slice, the rest is kept for the final answer. A FAILED status edit spends the
    # whole status budget (an edit-cap or rate-limit 400 means more would fail too),
    # so the final edit never races the cap.
    
  3. renderer.py, redaction notice

    Before:

    # Post-answer redaction notice, counted over the assembled answer the
    # chunks above were cut from (the reference shape iMessage uses). A
    # follow-up chunk that failed already announced its truncation, so a
    # count over the full content can at most describe a placeholder the
    # reader did not receive — the safe direction. Best-effort by the
    # shared contract: the answer is out, so a failed notice send is
    # logged, never raised.
    

    After:

    # Redaction notice, counted over the whole answer the chunks came from
    # (as iMessage does). If a follow-up chunk failed, the count may include
    # a placeholder the reader never got, which errs safe. Best-effort: the
    # answer is out, so a failed send is logged, never raised.
    
  4. transport_dispatch_commands.py, dashboard TTL

    Before:

    # parse_duration owns the <N>h / <N>m grammar and already clamps to the
    # server maximum; the outer min() keeps the clamp explicit at the call
    # site. A malformed duration falls back rather than erroring: the user
    # asked for a link, and refusing one over a typo trades a working link
    # for a lecture.
    

    After:

    # parse_duration owns the <N>h / <N>m grammar and already clamps to the
    # server maximum; min() keeps the clamp visible here. A malformed duration
    # falls back to the default instead of failing: the user asked for a link.
    

Backwards compatibility

Compatible: comments only; the AST of every changed file is unchanged.

Removes nothing: no code, test, docstring or check is removed.

Tests

Proof: not provable -- comment-only change; the AST check below shows no code moved.

  • goal_scan.py astcheck against the merge-base: 5 files checked, 0 code-changed, 0 docstring-only.
  • runtime_doc_check.py: 5 files, flagged 0.
  • check_comment_history.py and check_brand_name.py pass on the added lines; flake8 and black are clean; no added line is over 100 columns.

Manual verification

N/A — comment-only change.

Related Issues

N/A — part of the src comment cleanup.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributed under the project's Apache-2.0 license.

Shorten wordy comments in commands, renderer, client and two dispatch
helpers; keep each constraint and its reason. Comments only; no code
change.
@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners November 14, 2026 19:50
@iamwhatever
iamwhatever enabled auto-merge (squash) November 14, 2026 19:50
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 14, 2026
@github-actions

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision ac058626c031619bf4427afd4d200d3a66ee3073 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of ac058626c031619bf4427afd4d200d3a66ee3073 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

First-Principles-Verdict: PASS

Nothing to check.

What this change ships

Inventory (6 items) — 6 justified

Intent: help people and agents editing the Webex channel find each rule and its reason in fewer words. This is a FIX to the comments, and the code does not change.

  1. The _ALIAS_TO_COMMAND comment shrinks to a two-bullet list of the tests that read the aliases — justified
  2. The renderer.py comments on the edit budget, chunking, card message and redaction notice are shorter — justified
  3. The client.py comment on the scan-wait budget is shorter — justified
  4. The transport_dispatch_commands.py comment on the dashboard TTL fallback is shorter — justified
  5. The transport_dispatch_origin.py comment on the _CHANNEL drain name is shorter — justified
  6. No executable line changes in any of the five files — justified

[FIRST-PRINCIPLES-REVIEWED] ac05862

Description read

[DESCRIPTION-READ] e734bf5895badf8076d1d4478b93fdceb13d38cd282c88201d52f6138229c9ec

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of ac058626c031619bf4427afd4d200d3a66ee3073 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Comment-only change. Every added and removed line is a # comment, so no behaviour, contract or reader changes.

[DESIGN-REVIEWED] ac05862

Description read

[DESCRIPTION-READ] 9e868f8b930e55a9a9f1522a0182bdcba0c6a77f22e7ad14c8c0ff2c6bd47bd3

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed ac058626c031619bf4427afd4d200d3a66ee3073 — this comment is updated in place on each push.

Review details

No findings. The diff changes only comments in five src/kiro_crew/webex/ modules, so no runtime path changes.

Notes:

  • src/kiro_crew/webex/renderer.py:499: the comment says the redaction count covers "the whole answer the chunks came from", but the code counts delivered_text, the chunks that actually ship (see lines 437–439).

[OPUS-REVIEWED] ac05862

Verdict parsed from the review's SHA-scoped output markers for commit ac058626c031619bf4427afd4d200d3a66ee3073.

False positive or not applicable? A repository writer can comment:
/ai-review override fable ac058626c031619bf4427afd4d200d3a66ee3073 false-positive: <reason, 20 to 500 characters>

@github-actions

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of ac058626c031619bf4427afd4d200d3a66ee3073 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] ac05862

False positive or not applicable? A repository writer can comment:
/ai-review override gpt ac058626c031619bf4427afd4d200d3a66ee3073 false-positive: <reason, 20 to 500 characters>

@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider raised 1 possible problem and estimates a 50% chance that this change introduces a defect; a person should check it.

Comment-only PR in five webex modules; most rewrites keep their facts. But the rewritten redaction-notice comment in renderer.py says the count is over the source the chunks were cut from, as iMessage does. The code counts the shipped chunks (delivered_text), and the comment at lines 437-438 says so explicitly. The PR's stated goal is comments that are true, so this one should be fixed before merge.

Things to check (possible problems the decider raised; at this confidence many turn out to be fine):

  • The PR's only stated goal is to make these comments "short, plain and true" while keeping "the same facts". This rewritten comment repeats a false claim that contradicts the code and the comment 60 lines above it. An agent reading it would conclude the count is over the pre-chunk source, which is th (src/⁠kiro_crew/webex/renderer.py, low)

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit ac058626c0 · 104 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 14, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verified on this head: every changed line in the five src/kiro_crew/webex/ files is a comment. The parsed AST of each file matches the merge-base, so runtime behaviour cannot change. Docstrings are untouched, so the composition tests that read source through ast and inspect are unaffected. The rewritten commands.py alias comment names two test readers, and both exist: the getattr probe in test_messaging_dispatch.py and the *_ALIASES reflection in test_quick_prompts.py. PR Readiness is green.

Done well: the body states its own proof (AST identity), and that proof reproduces.

Optional:

  • src/kiro_crew/webex/renderer.py:499: the redaction-notice comment says the count runs over "the whole answer the chunks came from (as iMessage does)". The next line counts delivered_text, which is the shipped chunks, as the comment at lines 437-438 says. Suggested wording: "Redaction notice, counted over the chunks that shipped, so a placeholder a boundary repair added is counted too." Then drop "(as iMessage does)", because iMessage counts the whole answer. The old text had the same mistake, so this is not a regression.
  • src/kiro_crew/webex/renderer.py:430: the chunking comment no longer says that nothing upstream seals a code fence. That was the reason this split has to be fence-aware. A few words would bring it back.

@iamwhatever
iamwhatever merged commit 9db35e2 into main Nov 14, 2026
98 checks passed
@iamwhatever
iamwhatever deleted the crew/testoptimizer/src-quality-webex branch November 14, 2026 21:23
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants