Repository navigation
docs: tighten teams comments - #37328
Conversation
Shorten wordy comments in transport, renderer, gateway, commands and service_urls; keep each constraint and its reason. Comments only; no code change.
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: the patch only rewrites comments in five [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 |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing to check. What this change shipsInventory (5 items) — 5 justifiedIntent: 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).
[FIRST-PRINCIPLES-REVIEWED] a73aef0 Description read[DESCRIPTION-READ] 976cbf222ad7d1b73f132996ec643a58e94a134e838368bba3b1c4d3031473ac That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Code change approver recommendation: ApproveWhy: 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 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 |
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
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:303now says a serviceUrl "rarely changes". Two docstrings intest/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.pyandtransport_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.
Problem / Motivation
Goal: Make the
teamscomments 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
client.pyandtransport_dispatch.pyare skipped (open PRs fix(teams): send the token request and connector posts through the proxy #36691 and feat(redaction): scrub every persisted conversation row #36640 edit them).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.transport.pyfile capability bulletsrenderer.pyredaction noticegateway.pyconnect through the transportcommands.pymid-turn directivesservice_urls.pyre-mark on failed writeExamples:
transport.py,files_outboundBefore:
After:
service_urls.py, re-markBefore:
After:
gateway.py, connectBefore:
After:
commands.py, mid-turn directivesBefore:
After:
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 astcheckagainst the merge-base: 5 files checked, 0 code-changed, 0 docstring-only.runtime_doc_check.py: 5 files, flagged 0.check_comment_history.pyandcheck_brand_name.pypass 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
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributed under the project's Apache-2.0 license.