morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[GH-ISSUE #8290] [Design] Distinguish focused guidance matches from broad parent sections #6528

New issue

Closed

opened 2026-11-01 21:11:56 +00:00 by bsakaguchi · 3 comments

bsakaguchi commented

2026-11-01 21:11:56 +00:00

Owner

Originally created by @morluto on GitHub (Oct 31, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/8290

Originally assigned to: @kaoru0822-kitauji on GitHub.

Before submitting

I searched the open and closed issues and pull requests for a related discussion.
I understand the contribution scope must be reviewed before integration; open questions are welcome here.
This discussion does not include credentials, private samples, or sensitive target data.

Decision needed

Should guidance search treat a parent section's child sections as one match, or distinguish focused matches from terms scattered across different subsections before an agent reads the result?

Context and evidence

On REA b43c329 / installed guidance bundle rea-agents@6.8.0, public CLI and stdio MCP returned the same results without opening a target:

Search switch provider annotations: one match, the root section of references/native-and-artifacts.md, with matched_terms containing all three words. Reading its locator returned 49,189 characters. The first switch and provider occurrences were under Apple app resources; the first annotations occurrence was under Native targets. No direct explanation of whether switching providers retires edited Ghidra state was found in this returned guide.
Search Ghidra annotations: the first result was the focused Function annotations in Ghidra section; reading it returned 1,521 characters and explained that edits last until close. That section does not explicitly say switching providers closes the current database; the underlying lifecycle is tracked separately in #8289.
Search switch provider: the first hit was Apple app resources, a different workflow.

Source inspection shows the Markdown section parser intentionally includes all descendant subsections in a parent section, and matching gathers terms across that entire content. The result is consistent with that inclusive representation, but all terms need not occur in one focused recipe. The named source and guidance files were unchanged at main 23de10b. No model-selection failure or token measurement is claimed.

Expected interaction with targets

No target interaction (documentation or usability only).

Boundary details (optional)

Keep deterministic ordering, pagination, bundle identity, and stale-locator validation. Preserve access to complete parent material when intentionally requested; do not claim a missing focused match proves a capability is unavailable.

Options and tradeoffs

Consider indexing each section's own text separately from descendants, presenting explicit subtree matches, or ranking focused/co-located matches above broad parents. A truthful no-match may be more useful than an unrelated subtree match when no focused explanation exists. Retain a way to read the complete parent without introducing silent truncation. Evaluate normal multi-level Markdown and cross-heading use cases, not just this query.

Verification available so far

I have a prototype or observed results.

Success criteria and open questions

Test CLI and MCP search/read on real installed guidance with terms in one child, terms separated across siblings, heading-only terms, and an intentionally requested parent. Check full retrieval and continuation. Compare completed analyst lookup traces and token counts before claiming an agent-efficiency improvement.

References

Original search feature: https://github.com/morluto/rea/issues/6916. Annotation transition: https://github.com/morluto/rea/issues/8289.

Originally created by @morluto on GitHub (Oct 31, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/8290 Originally assigned to: @kaoru0822-kitauji on GitHub. ### Before submitting - [x] I searched the open and closed issues and pull requests for a related discussion. - [x] I understand the [contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope) must be reviewed before integration; open questions are welcome here. - [x] This discussion does not include credentials, private samples, or sensitive target data. ### Decision needed Should guidance search treat a parent section's child sections as one match, or distinguish focused matches from terms scattered across different subsections before an agent reads the result? ### Context and evidence On REA `b43c329` / installed guidance bundle `rea-agents@6.8.0`, public CLI and stdio MCP returned the same results without opening a target: - Search `switch provider annotations`: one match, the root section of `references/native-and-artifacts.md`, with `matched_terms` containing all three words. Reading its locator returned 49,189 characters. The first `switch` and `provider` occurrences were under `Apple app resources`; the first `annotations` occurrence was under `Native targets`. No direct explanation of whether switching providers retires edited Ghidra state was found in this returned guide. - Search `Ghidra annotations`: the first result was the focused `Function annotations in Ghidra` section; reading it returned 1,521 characters and explained that edits last until close. That section does not explicitly say switching providers closes the current database; the underlying lifecycle is tracked separately in #8289. - Search `switch provider`: the first hit was `Apple app resources`, a different workflow. Source inspection shows the Markdown section parser intentionally includes all descendant subsections in a parent section, and matching gathers terms across that entire content. The result is consistent with that inclusive representation, but all terms need not occur in one focused recipe. The named source and guidance files were unchanged at main `23de10b`. No model-selection failure or token measurement is claimed. ### Expected interaction with targets No target interaction (documentation or usability only). ### Boundary details (optional) Keep deterministic ordering, pagination, bundle identity, and stale-locator validation. Preserve access to complete parent material when intentionally requested; do not claim a missing focused match proves a capability is unavailable. ### Options and tradeoffs Consider indexing each section's own text separately from descendants, presenting explicit subtree matches, or ranking focused/co-located matches above broad parents. A truthful no-match may be more useful than an unrelated subtree match when no focused explanation exists. Retain a way to read the complete parent without introducing silent truncation. Evaluate normal multi-level Markdown and cross-heading use cases, not just this query. ### Verification available so far I have a prototype or observed results. ### Success criteria and open questions Test CLI and MCP search/read on real installed guidance with terms in one child, terms separated across siblings, heading-only terms, and an intentionally requested parent. Check full retrieval and continuation. Compare completed analyst lookup traces and token counts before claiming an agent-efficiency improvement. ### References Original search feature: https://github.com/morluto/rea/issues/6916. Annotation transition: https://github.com/morluto/rea/issues/8289.

bsakaguchi

2026-11-01 21:11:56 +00:00

closed this issue
added the
enhancement

triage
labels

bsakaguchi commented

2026-11-01 21:11:57 +00:00

Author

Owner

@morluto commented on GitHub (Oct 31, 2026):

For maintainer visibility: @gensokyo-dev @kaoru0822-kitauji @N0zoM1z0

@morluto commented on GitHub (Oct 31, 2026): For maintainer visibility: @gensokyo-dev @kaoru0822-kitauji @N0zoM1z0

bsakaguchi commented

2026-11-01 21:11:57 +00:00

Author

Owner

@kaoru0822-kitauji commented on GitHub (Oct 31, 2026):

Proposal (I'm picking this up; implementation PR to follow):

Index own text separately; keep the subtree for reading. The section parser additionally records each section's own text (its heading plus body before its first subsection) and its parent. read_guidance_section keeps returning the complete section including subsections, so complete parent material stays one read away, with no truncation.

Classify every match by where the terms occur. Admission is unchanged (every non-generic term occurs in the section's subtree). Each match then gets match_scope:

"section": every term occurs in the section's own text.
"subsections": the terms occur only across the section's own text and two or more of its subsections, with no single subsection containing them all.

Drop redundant ancestors. An ancestor whose own text lacks some terms, but which has one subsection containing all of them, is no longer listed. That subsection (or a deeper focused section) is already a result. Today every ancestor of a focused hit is listed too.

Rank focused matches first, then subtree matches, keeping the existing heading/term score and the "smaller section first" tie-break.

Make a subtree match explain itself before it is read. Subtree matches carry subsections: a small deterministic cover (at most one entry per query term) of the descendant sections whose own text contains the terms, each with heading, locator and matched_terms. Every match also reports characters, the size of what read_guidance_section would return. For switch provider annotations, the agent would see one "subsections" match for the 49K-character root, plus pointers to Apple app resources (switch, provider) and Native targets (annotations). It could then decide not to read 49K characters for an unrelated subtree.

Unchanged: deterministic ordering, pagination and cursors, bundle identity, stale-locator validation, the no-match wording. All changes are additive output fields. Matching moves from tokenising each expanded subtree to tokenising each own text once, so index work drops from expanded size (≤ 6× the bundle) to bundle size.

Verification plan: module tests for terms in one child, terms split across siblings, heading-only terms, terms in a parent's own text plus a child, fenced headings, and pagination continuity. Plus real CLI and stdio-MCP search/read on the installed bundle, with a before/after comparison of results and response sizes for the queries in this issue. I won't claim agent-efficiency gains beyond the measured response and read sizes.

@kaoru0822-kitauji commented on GitHub (Oct 31, 2026): Proposal (I'm picking this up; implementation PR to follow): **Index own text separately; keep the subtree for reading.** The section parser additionally records each section's *own text* (its heading plus body before its first subsection) and its parent. `read_guidance_section` keeps returning the complete section including subsections, so complete parent material stays one read away, with no truncation. **Classify every match by where the terms occur.** Admission is unchanged (every non-generic term occurs in the section's subtree). Each match then gets `match_scope`: - `"section"`: every term occurs in the section's own text. - `"subsections"`: the terms occur only across the section's own text and two or more of its subsections, with no single subsection containing them all. **Drop redundant ancestors.** An ancestor whose own text lacks some terms, but which has one subsection containing all of them, is no longer listed. That subsection (or a deeper focused section) is already a result. Today every ancestor of a focused hit is listed too. **Rank focused matches first**, then subtree matches, keeping the existing heading/term score and the "smaller section first" tie-break. **Make a subtree match explain itself before it is read.** Subtree matches carry `subsections`: a small deterministic cover (at most one entry per query term) of the descendant sections whose own text contains the terms, each with `heading`, `locator` and `matched_terms`. Every match also reports `characters`, the size of what `read_guidance_section` would return. For `switch provider annotations`, the agent would see one `"subsections"` match for the 49K-character root, plus pointers to `Apple app resources` (`switch`, `provider`) and `Native targets` (`annotations`). It could then decide not to read 49K characters for an unrelated subtree. Unchanged: deterministic ordering, pagination and cursors, bundle identity, stale-locator validation, the no-match wording. All changes are additive output fields. Matching moves from tokenising each expanded subtree to tokenising each own text once, so index work drops from expanded size (≤ 6× the bundle) to bundle size. Verification plan: module tests for terms in one child, terms split across siblings, heading-only terms, terms in a parent's own text plus a child, fenced headings, and pagination continuity. Plus real CLI and stdio-MCP search/read on the installed bundle, with a before/after comparison of results and response sizes for the queries in this issue. I won't claim agent-efficiency gains beyond the measured response and read sizes.

bsakaguchi commented

2026-11-01 21:11:57 +00:00

Author

Owner

@morluto commented on GitHub (Oct 31, 2026):

Existing-project lookup wording

On REA b43c329df779708e43ae297f498a844e45d9c923 with installed rea-agents@6.8.0, I tested the original project-loading question through the public CLI and stdio MCP guidance search; both returned the same first headings and counts for these queries. open ghidra project and existing ghidra project each ranked the focused Reuse caller-selected Ghidra analysis section first. Reading that locator returned the REA_GHIDRA_PROJECT_PATH / optional root-program setting, restart/reconnect instruction, read-only copied-project scope and unknown prior completeness.

load ghidra project instead returned Packages and extraction, REA, and the broad Native, managed, and packaged artifacts parent. Reading its first result did not contain REA_GHIDRA_PROJECT_PATH; the focused reuse section was not among the three results. loading ghidra project returned broad parent sections, not the focused heading. The unmodified search contract requires all non-generic query words to match, so this is a wording/section-index tradeoff, not proof the correct guidance is absent. Searching ghidra gzf returned no bundled section and explicitly warned that this does not establish capability availability.

This is a small scripted query/read control, not a model-selection or token-usage study. It suggests testing common task wording and focused-section discoverability alongside the sibling/parent cases already in this issue; a remedy could be guidance wording or search behavior and needs evaluation against false positives. The existing project scope and nested-program work remain separate in #3751 and #3817.

@morluto commented on GitHub (Oct 31, 2026): ### Existing-project lookup wording On REA `b43c329df779708e43ae297f498a844e45d9c923` with installed `rea-agents@6.8.0`, I tested the original project-loading question through the public CLI and stdio MCP guidance search; both returned the same first headings and counts for these queries. `open ghidra project` and `existing ghidra project` each ranked the focused **Reuse caller-selected Ghidra analysis** section first. Reading that locator returned the `REA_GHIDRA_PROJECT_PATH` / optional root-program setting, restart/reconnect instruction, read-only copied-project scope and unknown prior completeness. `load ghidra project` instead returned **Packages and extraction**, **REA**, and the broad **Native, managed, and packaged artifacts** parent. Reading its first result did not contain `REA_GHIDRA_PROJECT_PATH`; the focused reuse section was not among the three results. `loading ghidra project` returned broad parent sections, not the focused heading. The unmodified search contract requires all non-generic query words to match, so this is a wording/section-index tradeoff, not proof the correct guidance is absent. Searching `ghidra gzf` returned no bundled section and explicitly warned that this does not establish capability availability. This is a small scripted query/read control, not a model-selection or token-usage study. It suggests testing common task wording and focused-section discoverability alongside the sibling/parent cases already in this issue; a remedy could be guidance wording or search behavior and needs evaluation against false positives. The existing project scope and nested-program work remain separate in #3751 and #3817.

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

morluto/rea#6528

No description provided.

Rows
Columns