Skip to content

docs: tighten teams comments - #37328

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

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

Conversation

@iamwhatever

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Make the teams 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/teams/ take five to sixteen lines for one or two facts. This PR rewrites those comments. It changes no code.

Why it matters

Agents editing the Teams channel read these comments to learn why a capability is set, a store is re-marked or connect goes through the transport. A shorter comment with the same reason is easier to act on and to keep true.

Not a goal

What changed (motivation → approach → change)

Comments only, in five files: transport.py, renderer.py, gateway.py, commands.py, service_urls.py (29 lines added, 39 removed). Each rewrite keeps the same facts and the reason.

Where Kind of fix
transport.py file capability bullets wordy
renderer.py redaction notice wordy
gateway.py connect through the transport wordy
commands.py mid-turn directives wordy
service_urls.py re-mark on failed write wordy

Examples:

  1. transport.py, files_outbound

    Before:

    # * ``files_outbound=True`` -- and deliberately narrower than the platform. The
    #   renderer really does deliver a local raster the reply referenced, as an inline
    #   ``data:`` URI attachment, which needs no hosting and no round trip. A
    #   NON-image file would need the ``FileConsentCard`` flow: consent card, user
    #   accept, an ``invoke`` activity carrying an upload URL, then a PUT of the bytes.
    #   This channel's ingress fast-acks a message activity and dispatches a turn; it
    #   handles no ``invoke``, so that flow is out of scope here and a non-inlinable
    #   reference is refused visibly instead (see ``teams/attachments.py``).
    

    After:

    # * ``files_outbound=True`` -- narrower than the platform: the renderer sends a
    #   local raster the reply referenced as an inline ``data:`` URI. A NON-image file
    #   needs the ``FileConsentCard`` flow, which ends in an ``invoke`` activity; this
    #   ingress handles no ``invoke``, so such a reference is refused visibly (see
    #   ``teams/attachments.py``).
    
  2. service_urls.py, re-mark

    Before:

    # RE-MARK, because a transient failure must stay retryable. Leaving it
    # clear ends the retries entirely: ``remember`` only marks the map when
    # something CHANGES, and a conversation's serviceUrl is stable for its
    # lifetime -- so after one failed write the common case never marks it
    # again, nothing ever flushes, and the restart this store exists to
    # survive loses every proactive destination anyway.
    

    After:

    # RE-MARK so a transient failure stays retryable. ``remember`` marks
    # the map only on a CHANGE, and a serviceUrl rarely changes, so a
    # clear mark after one failed write means nothing flushes again and
    # a restart loses every proactive destination.
    
  3. gateway.py, connect

    Before:

    # Through the TRANSPORT, not the client directly: the transport's connect
    # primes the outbound token (validating the credentials and setting the
    # status badge via on_state_change, never raising) AND starts the
    # serviceUrl store warm-up. Calling the client's connect alone silently
    # skips the warm-up, which is what `configured_targets` -- a sync accessor
    # that cannot load the store itself -- depends on to report a Teams
    # destination as reachable after a restart.
    

    After:

    # Through the TRANSPORT, not the client: its connect primes the outbound
    # token (checks credentials and sets the status badge via
    # on_state_change, never raising) AND warms the serviceUrl store. The
    # client's connect alone skips the warm-up, and `configured_targets`, a
    # sync accessor that cannot load the store, then reports no reachable
    # Teams destination after a restart.
    
  4. commands.py, mid-turn directives

    Before:

    #: directive with no body is answered with usage rather than handed to the model,
    #: which would otherwise reply to the literal string ``/queue`` and be
    #: indistinguishable to the user from the feature not existing.
    

    After:

    #: directive gets a usage reply; sent to the model, ``/queue`` alone would get
    #: an answer that looks like the feature does not exist.
    

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 transport, renderer, gateway, commands and
service_urls; 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:52
@iamwhatever
iamwhatever enabled auto-merge (squash) November 14, 2026 19:52
@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 a73aef03866cec62104c2a4a03a3340908c7e7d9 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

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Nothing blocks: the patch only rewrites comments in five teams/ files, and each rewrite keeps the original facts and reasons.

[DESIGN-REVIEWED] a73aef0

Description read

[DESCRIPTION-READ] 46683bd2b5092f406c5dabca2942678fb2c55f39e9c71d44c250d1ecaa7947cf

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

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of a73aef03866cec62104c2a4a03a3340908c7e7d9 — 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 (5 items) — 5 justified

Intent: make the Teams channel's code comments shorter so maintainers and agents get each rule and its reason faster. This is an ADDITION (a clarity edit; no behaviour changes).

  1. Shorter comment on the files_inbound / files_outbound capabilities in transport.py — justified
  2. Shorter comment on the redaction notice in renderer.py — justified
  3. Shorter comment on why gateway.py connects through the transport — justified
  4. Shorter comment on the bare /queue and /steer usage reply in commands.py — justified
  5. Shorter comment on why service_urls.py re-marks the store after a failed write — justified

[FIRST-PRINCIPLES-REVIEWED] a73aef0

Description read

[DESCRIPTION-READ] 976cbf222ad7d1b73f132996ec643a58e94a134e838368bba3b1c4d3031473ac

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

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] a73aef0

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable a73aef03866cec62104c2a4a03a3340908c7e7d9 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 a73aef03866cec62104c2a4a03a3340908c7e7d9 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] a73aef0

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

@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: Approve

Why: the decider estimates a 3% chance that this change introduces a defect, within the 12% limit for approving on its own, and every check passes.

This PR only rewrites comments in five teams/ files. I read every hunk in the diff: each one changes # comment lines only, and no code or docstring is touched. Each shorter comment keeps the facts and the reason from the original. Among them: the personal-scope and allow-list gates come before inbound file downloads, the manifest must declare supportsFiles, a non-image outbound file is refused because the ingress handles no invoke, the transport's connect starts the serviceUrl store warm-up that configured_targets relies on (confirmed at transport.py:378-383), and the re-mark after a failed write keeps retries possible. The security notes the PR says it leaves alone are untouched. Since nothing executes differently, there is no state, lifecycle, limit or trust change to check.

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 a73aef0386 · 68 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.

Approved. Only comments change in this PR. On this head, the review parsed all five files with Python's ast module, at the merge-base and at the head. The trees are identical, so no code or docstring changed. The review checked the rewritten comments against the code. The flag order in ServiceUrlStore.flush matches, gateway.py still awaits transport.connect(), and the claim that invoke is not handled matches attachments.py. A search of test/, docs/, scripts/ and .github/ found no test that pins the removed wording. The security notes the body says it leaves alone are unchanged.

Done well: each shorter comment keeps the rule and its reason, and the PR skips the files that other open PRs edit, so it should not conflict with them.

Optional:

  • service_urls.py:303 now says a serviceUrl "rarely changes". Two docstrings in test/test_teams_service_urls.py (lines 47 and 216) still say it is "stable for its lifetime". You could keep the old wording here, or say in the PR that the change is on purpose.
  • #37333 edits client.py and transport_dispatch.py, the two teams files this PR skips. The two PRs share no files. Whoever merges them can check that #37333 does not conflict with #36691 or #36640.

@iamwhatever
iamwhatever merged commit 1f87adf into main Nov 14, 2026
100 of 101 checks passed
@iamwhatever
iamwhatever deleted the crew/testoptimizer/src-quality-teams branch November 14, 2026 21:47
@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