Repository navigation
docs: add context-management guide - #12156
Conversation
|
Intent: Give a maintainer one authoritative, code-derived account of what reaches the model's context — the first-turn block order, what repeats per turn, what a sub-agent sees, why a custom agent gets no skills, how a crew member's session is built, and which crew-member private files exist today. |
Opus 4.8 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 (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Spot-check the §1 block-order table against Suggestions
[DESIGN-REVIEWED] 5aa6bb0 |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 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: |
First Principles Review (Fable 5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS The test pins shares and four behaviour tables; the 20-row block order and per-turn table rest only on the author's read — spot-check those against What this change shipsInventory (7 items) — 7 justifiedIntent: let a maintainer answer "what is in the model's context" from docs instead of reading five modules — an ADDITION (with one declared doc fix riding in).
Verified: the eight share constants in [FIRST-PRINCIPLES-REVIEWED] 5aa6bb0 |
0e447af to
f7658e0
Compare
|
self-added: no
|
|
self-added: no
|
|
self-added: yes
|
|
self-added: no
|
|
self-added: no
|
f7658e0 to
6f06052
Compare
|
self-added: no
|
6f06052 to
4a4223b
Compare
|
self-added: yes
|
|
self-added: yes
|
|
self-added: yes
|
|
self-added: yes
|
|
self-added: no
|
The failing backend lanes are main-inherited, not this PREvery failing job dies at conftest import, before a single test in this diff The import chain that reaches it: Because the assert is at module scope, Why it is not this PR
What happens nextNo push, no job reruns, and nothing in Superseding my two earlier comments on this: the first implied that holding an |
|
self-added: yes
|
b855540 to
c241d02
Compare
|
Rebased onto
Two changes ride this single push, deliberately batched so one CI round judges both:
The pin moved rather than disappeared. The 12 byte assertions are gone; in their Verified on the new base before pushing: |
Answers six questions about what reaches the model, from current code: the first-turn block order, the per-turn additions, a sub-agent's scope, why a custom agent sees no skills, how a crew member's session is built, and which crew-member private files exist today. Cross-links agents/skills/subagents/memory docs and the module specs rather than restating them. Citations name a file and a symbol, since docs-lint rejects line numbers.
c241d02 to
5aa6bb0
Compare
|
self-added: yes
|
|
self-added: yes
|
|
Rebased onto All four traced to one defect I did not introduce.
Confirmed by bisecting rather than assuming: that test fails on a pristine This push also answers both open review items, and both were mine:
Every numeric share in the doc is now recomputed from live code, and no byte |
|
self-added: no
|
bolichen97
left a comment
There was a problem hiding this comment.
Approved: docs-class, and it ships the gate that keeps it honest rather than prose alone. Sampled test_context_management_doc.py: it pins the doc's stated shares and formulas against the LIVE constants (_PROTECTED_CONTEXT_CHARS_PER_TOKEN, _PROTECTED_CONTEXT_WINDOW_FRACTION, _PROTECTED_CONTEXT_FLOOR, MEMBER_BRIEFING_MAX_CHARS, _EPISODIC_MEMORY_CAP) and refuses byte literals in the shares table, so the doc names constants instead of quoting values that docs_lint.py would never re-check. That is the right answer to the failure mode the body itself names. Also corrects a real inaccuracy in an existing doc — memory-and-learning.md stated the decay table as if those history bodies reach the prompt. AGENTS.md router row added so a context.py change reaches the doc under the same-commit rule.
Answers six questions about what reaches the model, from current code: the first-turn block order, the per-turn additions, a sub-agent's scope, why a custom agent sees no skills, how a crew member's session is built, and which crew-member private files exist today. Cross-links agents/skills/subagents/memory docs and the module specs rather than restating them. Citations name a file and a symbol, since docs-lint rejects line numbers. Co-authored-by: Joe Guo <zejiangg@amazon.com>
Problem / Motivation
Nobody can answer "what is actually in the model's context right now?" from the
docs. The facts exist, but they are spread across
context.py,skills.py,subagent.py,members.pyand four module specs, so every question — what doesthe first turn carry, what repeats each turn, what does a sub-agent see, why does
a custom agent get no skills — needs a code read. Two questions have no written
answer at all: which crew-member private files exist today, and why a dispatched
kirocrew-workernever matches a skill trigger.Separately,
src/kiro_crew/docs/memory-and-learning.mdstates a decay table asif those history bodies reach the prompt. They do not: a new session carries a
bounded index and
memory_recallfetches bodies on demand.Why it matters
Getting this wrong wastes real work. A maintainer who believes daily history is
injected at session start debugs the wrong thing. A brief staged in
$KIROCREW_SCRATCHis unreadable to a dedicated-process sub-agent, which readsas a broken sub-agent. And a worker told to "follow the prepare-pr skill" cannot
find it, because its agent spec carries no
skill://entry — a silent gap thatcosts a whole dispatch.
A doc full of restated constants has its own failure mode, which is why this ships
a gate rather than just prose:
docs_lint.pychecks a doc's symbols and paths butnever its VALUES, so
858survives a change to_MEMORY_PREFS_CAPwith lintgreen and the doc quietly lying.
What changed (motivation → approach → change)
A new contributor document, a test that keeps it honest, a router row so a code
change reaches it, one corrected sentence in an existing doc, and cross-tree links
so readers still find it.
docs/architecture/context-management.mdtest/test_context_management_doc.pyAGENTS.mdcontext.py/context_blocks.pynow points here, so the same-commit update rule reaches this docsrc/kiro_crew/docs/memory-and-learning.mddocs/architecture/README.mdsrc/kiro_crew/docs/index.md,README.mdThe doc is ordered as the six questions a maintainer asks, with a table wherever
the answer has a shape: the first-turn block order and every budget with its
symbol; what repeats per turn and what returns after compaction; a sub-agent's
three
include_*switches and why its scratch dir differs; the four-rowskill-mapping table and what "lazy skill loading" means; a crew member's four
identity layers and the
session_createagent-inheritance rule; and aper-capability audit of crew-member private files marked implemented, partial or
not implemented with evidence.
It lives in
docs/architecture/rather than the packaged tree because it citesprivate symbols throughout, and
src/kiro_crew/docs/README.mdroutes anengineering note to
docs/. The packaged index links across with the repositoryURL every other packaged-to-contributor link already uses, since a relative path
would not resolve inside an installed wheel.
Two facts in it are easy to get backwards and are stated plainly: per-turn skill
trigger matching is off by default (
skills.max_triggeredis 0), and the[work ledger]snapshot rides on monitor / auto-nudge cycle messages, not onevery turn. Two orderings that a table alone would misreport are called out: a
Memory V2 member's essentials envelope is spliced in after the critical-rules
block ahead of every other row, and a mapped agent gets its skills on both
backends — only the loader differs, kiro-cli natively versus Kiro Crew injecting.
The test is what makes the numbers safe to restate. It reads the budgets table out
of the doc and asserts each literal equals the constant the same row names, then
asserts the behavioural tables against the code that implements them —
_skills_injection_planis called for all four rows rather than having its sourcescanned,
resourcesis asserted absent from_WORKER_MIRRORED_SHAPES, every_mark()label must appear in the timing list, and everyCAPABILITY_SECTIONSentry must appear in the permission row. A constant that moves, a new timing label
or a new capability section fails this test instead of silently aging the doc.
Citations name a file and a symbol, not
path:line, becausedocs_lint.py'sline-refcheck rejects line numbers and directs authors to cite a symbol.Backwards compatibility
Compatible: six markdown files and one new test. No code, schema, config key or
command changes. Nothing is removed from the wheel that was ever released in it —
the new doc never shipped in a release, and it was deliberately absent from
tips_allowlist.py, so it could not surface as an in-app feature tip.Tests
test/test_context_management_doc.py, 24 tests, all new. It pins SHARES, neverbyte figures, because
docs/system-specs/common/code-style.mdowns the rule thatcontext budgets are read as fractions of the base:
_budget(...)share from the live constants(
cap / _CONTEXT_BUDGET_BASE) and compare it to the percentage the doc states:_MEMORY_PREFS_CAP,_MEMORY_PROJECTS_CAP,_MEMORY_HISTORY_CAP,_LESSONS_CAP,_SEMANTIC_MEMORY_CAP,_SKILLS_CAP,_STEERING_CAP,_PREAMBLE_HEADROOM._HISTORY_BUDGET_CHARSand_COMPRESSED_HISTORY_CAPas shares of_HISTORY_REFERENCE_BASE.\d{1,3},\d{3}literal anywhere in the shares table, so bytefigures cannot drift back in beside a share.
activity_indexdefault, member capsand activity-log rotation are NAMED rather than quoted; that the
protected-ceiling factors and
MIN_TRIGGER_OVERLAPmatch; the three statedconfig defaults; the four-row skill-injection truth table, asserted by calling
_skills_injection_planrather than reading its source; the unmirroredresourceskey; completeCAPABILITY_SECTIONScoverage; and complete_mark()label coverage.
Every pin was proven to fail rather than merely pass, with the mutated file
restored byte-identical after each:
_SKILLS_CAP→_budget(0.20)test_share_table_matches_the_fraction_in_code[_SKILLS_CAP-6600]_HISTORY_BUDGET_CHARS→* 0.30test_history_shares_match_their_own_reference_base[_HISTORY_BUDGET_CHARS-49500]4,950to the skills rowtest_no_byte_literals_in_the_shares_tableManual verification
Every claim was read out of the code on this base, and an independent review pass
re-verified 38 of 38 of them against the same modules, finding none wrong.
python3 scripts/docs_lint.py --testand./scripts/docs-lint.sh→ pass, no new baseline triples. This is the gate that matters most here: the file moved between doc trees, which rewrote 11 relative links and required an index row, and link resolution plus reachability are exactly what it checks.run_scoped_tests.py --surface backend→ 24 passedcheck_brand_name.py,check_feature_map.py,check_changelog_history.py,check_comment_history.py,check_testpaths_coverage.py,check_per_file_coverage.py,check_sync_io_in_async.py→ passblack --checkandflake8on the new test file → cleanSpot-checked on this host:
~/.kiro/agents/kirocrew-worker.jsoncarriesresources: ["file://.kiro/steering/**/*.md"]and noskill://entry, which isthe §4 claim; and a member directory holds
activity.jsonlwithbriefing.mdabsent until written, which is the §6 claim.
Related Issues
no linked issue: documentation gap raised directly, not tracked as an issue.
Checklist
feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)