Repository navigation
docs: close the context-management guide's deferred follow-ups - #21106
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing to check. [DESIGN-REVIEWED] b924652 Description read[DESCRIPTION-READ] f28f04e058cdfc5ec9a110493ad150a5715b63a6f8b6a07277331c19806f42e5 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 Check that the anchors What this change shipsInventory (4 items) — 4 justifiedIntent: keep the context-management guide's block-order table in step with the code, and make the guide findable from the specs that overlap it. This is a FIX for issue #12175.
The memory-and-learning user doc's sentence about the activity index now says excerpts (headings, bullets, first lines) instead of headings — justified [FIRST-PRINCIPLES-REVIEWED] b924652 Description read[DESCRIPTION-READ] 1ee515e7678cddeba51d69cab88d81c785eea1111fd94d2fc072b71b44b2c82c 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: |
Pin the guide's first-turn block-order table against context_blocks._MARKERS, with an explicit allowlist of the markers the table deliberately leaves to section 2 or to callers outside build_session_context, so a new block cannot leave the table silently incomplete. Add a see-also from the crew-mode, subagent and memory-skills-hooks specs to the guide, so an author editing one finds the doc that restates it, and describe the memory activity index as the excerpts it carries rather than headings only. Closes #12175
f6c7dd7 to
b924652
Compare
mbriones98
left a comment
There was a problem hiding this comment.
Checks green and readiness passed at b924652; no behavior change.
Problem / Motivation
Goal: Close the follow-ups deferred from the context-management guide (#12156) that are still open on main, so the guide's block-order table cannot silently fall behind
_MARKERSand authors editing the overlapping specs can find the guide.The guide's first-turn block-order table was prose only: adding a block to
context_blocks.py::_MARKERSfailed nothing. The crew-mode and subagent specs had no pointer to the guide, and memory-skills-hooks only linked it deep inside the file. The user docmemory-and-learning.mdsaid the activity index carries "headings", whileMemoryStore.activity_indexalso carries bullets and each paragraph's first line.Why it matters
A guide that restates code facts is only trustworthy while something fails when those facts change. Without the pin and the backlinks, the table goes stale silently and authors of the overlapping specs never learn the guide exists.
Not a goal
What changed (motivation → approach → change)
test/test_context_management_doc.py: one test,test_block_order_table_names_every_marker, mirroring the existing_mark()completeness test. Every_MARKERSlabel must match a row of the §1 block-order table (using the marker's own regex) or appear in_BLOCK_ORDER_OMITTEDwith the reason it is omitted (owned by §2, rendered inside the memory-family row, the session wrapper, or prefixed by a caller outsidebuild_session_context). Stale allowlist entries (label gone from_MARKERS, or now has a row) also fail, so the allowlist cannot turn into a blanket waiver. An entry whose reason says §2 owns it must also match somewhere in §2 (design-review suggestion).docs/system-specs/modules/{crew-mode,subagent,memory-skills-hooks}.md: one "See also" line each, pointing at the guide (at §5 and §3 for crew-mode and subagent).src/kiro_crew/docs/memory-and-learning.md: "a bounded index of the last three days' headings" now says excerpts (headings, bullets and each paragraph's first line), matchingactivity_index.Backwards compatibility
Compatible: docs and one new test only; no runtime code changes.
Removes nothing: the diff only adds a test and doc lines and rewords one sentence.
Tests
test_block_order_table_names_every_marker: pins the §1 block-order table against_MARKERS. Checked by hand that it fails when a table row is removed, when a marker is neither in the table nor allowlisted, when an allowlist entry goes stale, and when a "§2" block is dropped from §2.test/test_context_management_doc.py(25 passed), plustest_adaptive_startup_memory.py,test_admission_gate.py,test_members_preview_speech_only.py(the tests that read the edited docs; 212 passed in total),test_flake_pattern_ratchet.py(58 passed),scripts/docs-lint.sh, black, isort, flake8, the comment-history and brand gates.Manual verification
N/A: docs plus a static doc-vs-code test, and unit coverage exercises it.
Related Issues
Closes #12175
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; see the Licensing section of CONTRIBUTING.md.