Skip to content

docs(monitoring): shorten long comments and docstrings - #31452

Merged
iamwhatever merged 2 commits into
mainfrom
crew/testoptimizer/src-monitoring-wordy
Nov 6, 2026
Merged

iamwhatever merged 2 commits into
mainfrom
crew/testoptimizer/src-monitoring-wordy

Conversation

@iamwhatever

Copy link
Copy Markdown
Contributor

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

  • No code or behaviour change.
  • No edit to comments about trust, untrusted provider data or credentials (in models.py: the key-space prefix block, the short-reading digest bound, use_owner_credentials, the public observation projection; in github_pull_request.py: the probe docstring and the one-credential-per-host query notes, and the REST path block about validated targets and no provider-controlled text).
  • monitoring/pull_request.py and the remaining wordy blocks in github_pull_request.py are 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:

  1. 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.
  2. 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_key and _run_was_cancelled. A reference to the replaced last_wake_fingerprint comparison is dropped.

Comment lines in monitoring (comment_scan.py lines): 2081 -> 1917 (after commit 1) -> 1802 (after commit 2).

goal_scan.py astcheck against 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.monitoring pass: 4,540 passed, 0 failed. flake8, the brand gate and scripts/check_comment_history.py pass on the changed files.

Manual verification

N/A — comment-only change, proven by the AST check.

Related Issues

N/A

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

Contributions are accepted under the project's Apache-2.0 license.

@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners November 6, 2026 14:10
@iamwhatever
iamwhatever requested a review from Zedmor November 6, 2026 14:10
@iamwhatever
iamwhatever enabled auto-merge (squash) November 6, 2026 14:10
@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 36d0079

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

@github-actions

github-actions Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

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

@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Nov 6, 2026
@iamwhatever
iamwhatever disabled auto-merge November 6, 2026 16:18
@iamwhatever
iamwhatever force-pushed the crew/testoptimizer/src-monitoring-wordy branch from c0f3527 to 36d0079 Compare November 6, 2026 16:21
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Rebased on main to pick up #31469, which fixes the shard 2 security line-budget test. New head 36d0079. astcheck code-changed 0, runtime_doc_check flagged 0, comment-history and brand gates passed, 95 monitoring test files: 4,540 passed.

@iamwhatever
iamwhatever enabled auto-merge (squash) November 6, 2026 16:21
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 6, 2026
@github-actions

github-actions Bot commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

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 .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

github-actions Bot commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 36d00799bad441e7158656fbdf799beb232433b8 — 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

Comment-only cleanup. Nothing blocks: no code, default, surface or pin changes.

What this change ships

Inventory (3 items) — 3 justified

Intent: make the monitoring package's comments short enough to read while keeping each reason. This is an ADDITION (a copy edit).

  1. The comments and docstrings in monitoring/models.py are shorter, and the lines describing old code now state the current rule — justified
  2. The comments on the stall, coalescing and digest helpers in monitoring/decision.py are shorter — justified
  3. The supersession and cancel-detection comments in monitoring/github_pull_request.py are shorter — justified

[FIRST-PRINCIPLES-REVIEWED] 36d0079

Description read

[DESCRIPTION-READ] e2afb5acee05eca42cd8125581dfef1ba70928a8fcef25073f182529aafe89e9

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

github-actions Bot commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings. The diff only rewrites comments and leading docstrings in three monitoring/ modules. With docstrings blanked, the ASTs of all three files match before and after, so the code runs the same.

[OPUS-REVIEWED] 36d0079

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

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

@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 6, 2026

@buluoray buluoray left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🤖 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.

@iamwhatever
iamwhatever merged commit 6b0b46b into main Nov 6, 2026
98 checks passed
@iamwhatever
iamwhatever deleted the crew/testoptimizer/src-monitoring-wordy branch November 6, 2026 18:56
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 6, 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