Document the leaf-first investigation contract in Internals.md #72

New issue

Closed

opened 2026-04-11 10:57:21 -06:00 by claude-code · 0 comments

claude-code commented

2026-04-11 10:57:21 -06:00

Collaborator

Phase 3 prep. The dir loop's _get_child_summaries() function silently depends on directories being investigated leaves-first: when the loop runs on a parent dir, it reads cached summaries for each subdirectory and injects them into the parent's system prompt. Those subdirectory summaries only exist because the children were investigated first.

This is load-bearing but invisible. Phase 3's planning pass will be tempted to introduce alternative orderings ("priority-first", "breadth-first" — both mentioned in PLAN.md Part 4). If a parent runs before its children, the child-summary lookup quietly returns nothing and the parent's system prompt gets an empty (none — this is a leaf directory) placeholder. The agent has no way to know it lost context. The dir summary degrades and synthesis inherits the degradation.

Fix

Add a short note in docs/wiki/Internals.md (most likely as a new §4.7 right after the streaming API caller, or as an expansion of §4.3 where _get_child_summaries() is already discussed) that:

Explicitly states _discover_directories() returns leaves-first ordering
Explicitly states _get_child_summaries() depends on that ordering
Names the failure mode if order changes (silent context loss → degraded summary)
Lists the two ways to safely change the order: (a) preserve leaf-first within priority bands or (b) handle the missing-child-summaries case explicitly in the prompt

Notes

Discovered during Phase 3 prep recommendations
The actual #70 test class TestDiscoverDirectories already pins the ordering, but the reason the ordering matters lives in code comments and oral tradition only
No code change. Wiki only.

Phase 3 prep. The dir loop's `_get_child_summaries()` function silently depends on directories being investigated leaves-first: when the loop runs on a parent dir, it reads cached summaries for each subdirectory and injects them into the parent's system prompt. Those subdirectory summaries only exist because the children were investigated first. This is load-bearing but invisible. Phase 3's planning pass will be tempted to introduce alternative orderings ("priority-first", "breadth-first" — both mentioned in PLAN.md Part 4). If a parent runs before its children, the child-summary lookup quietly returns nothing and the parent's system prompt gets an empty `(none — this is a leaf directory)` placeholder. The agent has no way to know it lost context. The dir summary degrades and synthesis inherits the degradation. ## Fix Add a short note in `docs/wiki/Internals.md` (most likely as a new §4.7 right after the streaming API caller, or as an expansion of §4.3 where `_get_child_summaries()` is already discussed) that: - Explicitly states `_discover_directories()` returns leaves-first ordering - Explicitly states `_get_child_summaries()` depends on that ordering - Names the failure mode if order changes (silent context loss → degraded summary) - Lists the two ways to safely change the order: (a) preserve leaf-first within priority bands or (b) handle the missing-child-summaries case explicitly in the prompt ## Notes - Discovered during Phase 3 prep recommendations - The actual #70 test class `TestDiscoverDirectories` already pins the ordering, but the *reason* the ordering matters lives in code comments and oral tradition only - No code change. Wiki only.