Repository navigation
docs(agent_sdk): shorten long comments and docstrings - #31643
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
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: |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing to check. Only comments and one docstring change. Each block keeps its rule, its reason and its evidence pointer, and the source line the deepseek test reads is still intact. [DESIGN-REVIEWED] 7b8c609 Description read[DESCRIPTION-READ] e52a30847b22f23a423e85a15fc9b3ba2d328e5db370b6ddd3173bac1c06c808 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 (4 items) — 4 justifiedIntent: make the harness-membership comments in three
[FIRST-PRINCIPLES-REVIEWED] 7b8c609 Description read[DESCRIPTION-READ] 8cbeffe972e8255ad0c544f15fe06017af54d9713246e5e98e7ac2b9c57638c5 That sha256 names the PR description this verdict read. Recompute it with |
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: |
116c378 to
d168727
Compare
d168727 to
7b8c609
Compare
bolichen97
left a comment
There was a problem hiding this comment.
Approving head 7b8c609. The gate showed 94 checks passed. The three red ones, PR Readiness, Sensitive Change Review and Dependency License Gate, failed on the GitHub API rate limit, and their reruns passed.
This is comments and docstrings only. I parsed each of the 3 changed agent_sdk backend files at the merge base and at this head, removed docstrings, and compared the ASTs. All 3 are identical, so no code changed.
Problem / Motivation
Goal: Make the harness membership comments in
agent_sdk/backends_turns.py,agent_sdk/backends_mcp.pyandagent_sdk/backends_routing.pyshorter and easier to read, with no code change.Several membership comments take 30 to 110 lines to say which harnesses belong to a set and why. They repeat the same point, retell how a conclusion was reached, and keep superseded measurements next to the committed fixture that replaced them.
Why it matters
These sets decide how Crew steers, compacts, routes MCP settings and gates tool approval per harness. A reader who has to work through 100 lines of narrative to find the rule is more likely to misread it.
Not a goal
backends.py,backends_members.py,agent_specs.py,tool_gate.pyorhost_auth.py.backends_models.pyandbackends_sessions.pyare left for a later pass.What changed (motivation → approach → change)
Each comment keeps its rule, the reason for it, and the evidence (version, fixture path, the observed result). What goes: repeated statements, narration of how the conclusion was reached, and numbers that a committed fixture now covers.
backends_turns.pyACP_BACKENDS_STEER,ACP_BACKENDS_STEERING_REQUEST,ACP_BACKENDS_COMPACT,ACP_BACKENDS_HARNESS_MANAGED_COMPACTION,ACP_BACKENDS_CONTEXT_RECYCLE,ACP_BACKENDS_INLINE_COMPACTIONbackends_mcp.pyACP_BACKENDS_EFFORT_OVERLAY,ACP_BACKENDS_CLIENT_META_SETTINGSbackends_routing.pyACP_BACKENDS_SIDE_READONLY(one bullet per member, the later per-harness paragraphs folded in),ACP_BACKENDS_META_IDENTITY,ACP_BACKENDS_PERMISSION_KIND_FROM_TOOL_CALL,ACP_BACKENDS_HOST_AUTH_CALLBACK, and theSEEDED_SETTINGS,VERIFIED_SEEDED_SETTINGSandVERIFIED_GATE_EXTENSIONentries of theRoutingdocstringcomment_scan.py lines --root src/kiro_crew --pkg agent_sdk: 8896 -> 8712 comment lines.goal_scan.py astcheck <merge-base>:files checked: 3 code-changed: 0 docstring-only: 1. The one docstring touched isRouting's, which nothing reads at runtime (no__doc__orgetdocuse). TheCaptured on dsh 0.2.0-rc.2 withline thattest_acp_deepseek_backend_session.pyreads from the source is kept on one line.Backwards compatibility
Compatible: comments and one docstring only; the AST of all three files is otherwise unchanged.
Removes nothing: no code, key, record or function is touched.
Tests
Proof: not provable -- docs or config only
After a rebase on main, the 297 test files that name
agent_sdk(pytest -n 4): 15,926 passed, 101 failed. The same 101 fail onorigin/mainon this host (the copilot tool-gate refusal andPlatformCompositionErrorintest_acp_*files), so they are not from this change. flake8, the brand gate andscripts/check_comment_history.pypass on the changed files.Manual verification
N/A — comment-only change, checked with astcheck, flake8,
scripts/check_comment_history.pyand a 100-column check on added lines.Screenshots / video
N/A — no frontend file is touched.
Related Issues
N/A
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement