Repository navigation
docs: tighten metrics, session_parts and channel comments - #37333
Conversation
Shorten wordy comments in member_space, the Webex and Teams dispatchers, the Teams client and the WhatsApp renderer, and move one misplaced Teams note onto the argument it explains. Comments only; no code change.
Shorten wordy comments in metrics provider and events and in session_parts record and policy, and state two notes as current rules instead of their history. 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 changes comments, and the comment move in [DESIGN-REVIEWED] 7ae1222 Description read[DESCRIPTION-READ] d2c622935ab764ba70adddf17aa1eaa5829f16270d0ba6924aa2f50b73aff06f 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 blocks. Only comments change, no code or default moves, and no comment that warned against a change was weakened or reversed. What this change shipsInventory (7 items) — 7 justifiedIntent: make comments in the metrics, session-state and channel files shorter and accurate, so a reader gets each rule and its reason quickly. This is a FIX, to the comments only.
[FIRST-PRINCIPLES-REVIEWED] 7ae1222 Description read[DESCRIPTION-READ] afed70f9310d28f5c2ae97f6ea3e28da3992a5fb51f1df6899ff590c0d963eab 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: |
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Approving. On this head, the review parsed all 9 changed files at the merge-base and at 7ae1222 and found the Python AST identical in every file, so this changes comments only. No added line is over 100 columns. No test pins the removed wording. The details the rewrite drops (the WhatsApp completing-span note, the Make-Live drain incident) are still documented in the turn renderer and the session spec.
Done well: the Teams session-attribution warning now sits on the exact conversation_id=f"teams:{email}" argument it guards, and the metrics comments now state the current rule instead of narrating history.
- Optional: in
members_parts/member_space.py, "nothing grows it" sits next to "the file stays agent-writable". "No Kiro Crew writer grows it" would remove that tension. - Optional: in
teams/client.py, "webhook / card limit" can read as covering bot cards too. "Incoming-Webhook / message-extension card limit" keeps the original distinction. - Optional: #37183 edits
metrics/provider.pyjust above the reader comment, so whichever lands second may need a small rebase.
Problem / Motivation
Goal: Make comments in
metrics,session_partsand six channel/member files short, plain and true, so a reader (person or AI agent) gets each rule and its reason in fewer words.Several comments in these files take eight to twenty-three lines for a few facts, two describe history instead of the current rule, and one Teams note sits far from the argument it explains. This PR rewrites those comments. It changes no code.
Why it matters
Agents editing telemetry, session state and the channel dispatchers read these comments to learn why an import is lazy, a lease stays armed or a field is chosen. A shorter comment that states the current rule is easier to act on and to keep true.
Not a goal
What changed (motivation → approach → change)
Comments only, in nine files (77 lines added, 106 removed), in two commits: one for files other open PRs also touch, one for
metricsandsession_parts.metrics/provider.pylazy SDK import, embed buckets, reader reap, install idmetrics/events.pywebhook countersession_parts/record.pyreplay leasesession_parts/policy.pydrain timeoutmembers_parts/member_space.pylegacy activity fileteams/transport_dispatch.pyconversation_idnote onto that argument; split a glued noteteams/client.py,webex/transport_dispatch.py,whatsapp/renderer.pyExamples:
metrics/provider.py, embed buckets (history)Before:
After:
session_parts/policy.py, drain timeout (history)Before:
After:
metrics/provider.py, reader reapBefore:
After:
teams/transport_dispatch.py, misplaced noteBefore (above
_surface_new_session, 30 lines from the argument):After (on the argument itself):
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: 9 files checked, 0 code-changed, 0 docstring-only.runtime_doc_check.py: 9 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.