Repository navigation
docs(monitoring): shorten long comments and docstrings - #31452
Conversation
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: |
UX Review (Opus 5.5) — ⏭️ skippedRevision |
c0f3527 to
36d0079
Compare
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS No code changes: every hunk across the three monitoring files is a comment or docstring, and nothing renders. [DESIGN-REVIEWED] 36d0079 Description read[DESCRIPTION-READ] dea1e814eae4a96356adaf8226c385f5873d58c93e9bc8d5ca9b747231b04c0a 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 Comment-only cleanup. Nothing blocks: no code, default, surface or pin changes. What this change shipsInventory (3 items) — 3 justifiedIntent: make the monitoring package's comments short enough to read while keeping each reason. This is an ADDITION (a copy edit).
[FIRST-PRINCIPLES-REVIEWED] 36d0079 Description read[DESCRIPTION-READ] e2afb5acee05eca42cd8125581dfef1ba70928a8fcef25073f182529aafe89e9 That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Review detailsNo findings. The diff only rewrites comments and leading docstrings in three [OPUS-REVIEWED] 36d0079 Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
buluoray
left a comment
There was a problem hiding this comment.
🤖 Kiro Crew Auto-Pipeline [operator: buluoray]:
APPROVE: comment and docstring trims only; no executable code changed and the shortened comments I checked still match the code and constants.
What it does: shortens the long comments and docstrings in the monitoring engine (stall streak, coalescing window, check supersession, MonitorState fields), keeping the reasoning while cutting about half the words. No behaviour change.
Evidence
- Executable code: compared ast.dump of the merge base (89a6107) and the head for all 3 changed files (monitoring/decision.py, github_pull_request.py, models.py) after removing the leading docstring of every module, class and function. All 3 identical, 0 mismatches. 17 docstrings changed, all on internal engine functions, enums, dataclasses and the MonitorProbe protocol; none is an MCP tool or CLI command description, and these classes are plain enums and dataclasses, not schema-generating models, so no docstring reaches a model-facing description.
- Lint and suppression markers: none in these files before or after.
- Docstrings read by tests: none read doc from these modules. monitor_stall_reason's docstring names test_monitor_controller_realert_stall, which still exists.
- Spot-checked shortened comments against code: "6 < 12 < 48" (stall floor 1800 / cadence 300 = 6, DEFAULT_MONITOR_STALL_TICKS 12, runtime 14400 / 300 = 48); "240 << 1800 << 21600" (coalesce 240.0, stall floor 1800, re-alert 6 x 3600); cadence 15 to 86400 with default 300; "twelve ticks at 15s is 165s" (eleven intervals, as the original said); 25 subjects per query (github_pull_request.py:90) for the 2,500-node figure; MAX_MONITOR_FIXED_CONDITIONS 5 as four co-occurring keys plus one margin; the RECORD_ONLY at 15s reaching twelve ticks 180s into a 240s window; the IMMEDIATE severity bypassing the delay but not the mask; the cancelled-run supersession rule; the provider-error skip note. All accurate.
- CI on 36d0079: 94 check runs, 76 success, 18 skipped, 0 failed; PR Readiness success. All five bot lanes pass or skip. git merge-tree against current main: clean.
- Not run: no tests executed locally; CI results were read instead.
Problem / Motivation
Goal: Make the comments in
src/kiro_crew/monitoring/short enough to read, keeping every reason a reader needs.Many comments and docstrings in the monitoring models, decision policy and GitHub pull-request adapter take ten or more lines to say one thing, and some describe how the code used to look instead of the rule it follows now.
Why it matters
Long comments hide the rule a reader needs, so the real constraints in this package (stall bounds, coalescing and re-alert masks, fail-safe normalisation, key spaces, check-run supersession) are easy to miss.
Not a goal
models.py: the key-space prefix block, the short-reading digest bound,use_owner_credentials, the public observation projection; ingithub_pull_request.py: theprobedocstring and the one-credential-per-host query notes, and the REST path block about validated targets and no provider-controlled text).monitoring/pull_request.pyand the remaining wordy blocks ingithub_pull_request.pyare left for a later PR.What changed (motivation → approach → change)
Wordy comment → cut to the lines that carry the reason → rewrite as the rule. Two commits:
src/kiro_crew/monitoring/models.py: 25 comment and docstring blocks rewritten (130 lines added, 294 removed). History wording ("two scalars held the window before this", "the original carried", "was considered and rejected") is rewritten as the rule.src/kiro_crew/monitoring/decision.py(110 added, 199 removed): the stall-streak constants,decide_monitor,_verdict_digest,_verdict_is_settled,_stall_tripped,_fold_stall_streak, the head-change reset,_window_entries,_reset_revision_memory,_coalesce_actionable,monitor_stall_reason(its three-part invariant kept) and the unattempted-probe comment.src/kiro_crew/monitoring/github_pull_request.py(29 added, 55 removed): the PR-level comment page block,_superseded_keyand_run_was_cancelled. A reference to the replacedlast_wake_fingerprintcomparison is dropped.Comment lines in
monitoring(comment_scan.py lines): 2081 -> 1917 (after commit 1) -> 1802 (after commit 2).goal_scan.py astcheckagainst the merge-base:files checked: 3 code-changed: 0 docstring-only: 3. The changed docstrings are on dataclasses, enums and private helpers; none is read at runtime (no__doc__, CLI help or tool description reads them).Backwards compatibility
Compatible: only comments and docstrings changed; the AST of the code is identical.
Removes nothing: no code, key, field or public function changes.
Tests
Proof: not provable -- copy-only change
After a rebase on main, the 95 test files that import
kiro_crew.monitoringpass: 4,540 passed, 0 failed. flake8, the brand gate andscripts/check_comment_history.pypass on the changed files.Manual verification
N/A — comment-only change, proven by the AST check.
Related Issues
N/A
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributions are accepted under the project's Apache-2.0 license.