Skip to content

docs: close the context-management guide's deferred follow-ups - #21106

Merged
iamwhatever merged 1 commit into
mainfrom
fix/12175-context-guide-followups
Oct 17, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
fix/12175-context-guide-followups

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

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 _MARKERS and 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::_MARKERS failed 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 doc memory-and-learning.md said the activity index carries "headings", while MemoryStore.activity_index also 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

  • Item 2 (widening the AGENTS.md router rows): the issue offers item 3's backlinks as the cheaper option covering the same gap; this PR takes that option.
  • Item 4 (packaged README links): already absolute GitHub URLs on main, nothing to change.
  • Adding new block-order rows for markers the table deliberately omits.

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 _MARKERS label must match a row of the §1 block-order table (using the marker's own regex) or appear in _BLOCK_ORDER_OMITTED with the reason it is omitted (owned by §2, rendered inside the memory-family row, the session wrapper, or prefixed by a caller outside build_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), matching activity_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.
  • Run locally: test/test_context_management_doc.py (25 passed), plus test_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

  • 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; see the Licensing section of CONTRIBUTING.md.

@github-actions

github-actions Bot commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision b924652a7ecdc1856a355611112e853e5c6a9153 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 16, 2026
@github-actions

github-actions Bot commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of b924652a7ecdc1856a355611112e853e5c6a9153 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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 .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 Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of b924652a7ecdc1856a355611112e853e5c6a9153 — 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/CONCERNS are advisory.

First-Principles-Verdict: PASS

Check that the anchors #5-crew-mode-crew-page and #3-sub-agent-sessions-spawn_run resolve against the guide's current headings.

What this change ships

Inventory (4 items) — 4 justified

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

  1. A test now fails when a _MARKERS block is missing from the §1 table, when an allowlist entry goes stale, or when a block the allowlist says §2 owns is not named in §2 — justified
  2. The crew-mode spec gains a "See also" link to guide §5 — justified
  3. The subagent spec gains a "See also" link to guide §3 — justified
  4. The memory-skills-hooks spec gains a "See also" link to the guide near its top — justified

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 .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 Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] b924652

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable b924652a7ecdc1856a355611112e853e5c6a9153: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] b924652

False positive or not applicable? A repository writer can comment:
/ai-review override gpt b924652a7ecdc1856a355611112e853e5c6a9153: <one-sentence reason>

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
@iamwhatever
iamwhatever force-pushed the fix/12175-context-guide-followups branch from f6c7dd7 to b924652 Compare October 16, 2026 06:59
@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 Oct 16, 2026

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

Checks green and readiness passed at b924652; no behavior change.

@iamwhatever
iamwhatever merged commit bf050b7 into main Oct 17, 2026
104 of 112 checks passed
@iamwhatever
iamwhatever deleted the fix/12175-context-guide-followups branch October 17, 2026 05:25
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 17, 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.

docs: follow-ups deferred from the context-management guide (#12156)

2 participants