Skip to content

Commit b2edd46

Browse files
HumanBean17cursoragent
HumanBean17
and
cursoragent
committed
propose: v4 success-path hints for neighbors, find, and search
Documents locked templates and triggers for issue #163; no implementation. Co-authored-by: Cursor <cursoragent@cursor.com>
1 parent 87259bb commit b2edd46

1 file changed

Lines changed: 199 additions & 0 deletions

File tree

‎propose/HINTS-V4-SUCCESS-PATH-PROPOSE.md‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
# HINTS-V4 — success-path road signs for `neighbors`, `find`, and `search`
2+
3+
## Status
4+
Proposal — not yet implemented. Tracks [issue #163](https://github.com/HumanBean17/java-codebase-rag/issues/163).
5+
6+
## Problem Statement
7+
8+
Real-codebase agent traces show `hints: []` on most **successful** tool calls. The landed catalog (v1 + #161 producer amendments + v2 `resolve`/fuzzy + v3 empty-neighbors structural) is heavily weighted toward recovery:
9+
10+
| Tool | Success-path coverage today |
11+
|---|---|
12+
| `describe` | Strong for type/method rollups, route/client/producer declaring-method rows |
13+
| `neighbors` | Non-empty: fuzzy-strategy meta only; empty: v3 structural rows |
14+
| `find` | Page-full and empty→`resolve` only |
15+
| `search` | Weak-score spread only |
16+
| `resolve` | `none` / `many` only (`one` correctly silent) |
17+
18+
That violates the original frame in `propose/completed/HINTS-ROAD-SIGNS-PROPOSE.md` §1: hints attach to **all outputs**, not only errors. The highest-friction workflow in production is the happy path where the agent must chain tools (class → members → clients → `HTTP_CALLS` → route handler) without ever calling `describe` on the type first — so it never sees the v1 type-rollup hints.
19+
20+
Concrete failure mode (observed on brownfield corpora):
21+
22+
1. Agent calls `neighbors([class_id], 'out', ['DECLARES'])` and gets method `NodeRef`s — **no hint**.
23+
2. Agent guesses `neighbors([class_id], 'out', ['DECLARES_CLIENT'])` on the type id — empty + v3 type-level requery (late).
24+
3. Correct path (`DECLARES` → member ids → `DECLARES_CLIENT` / `EXPOSES`) is only documented inline when the agent happened to `describe` the class earlier.
25+
26+
Issue #163’s candidate table is directionally right but needs tightening against road-sign discipline (char cap, tone, payload limits, cap interaction). Producer symmetry (#161) is already on the `describe` side; v4 must mirror it on `neighbors` success chains.
27+
28+
## Proposed Solution
29+
30+
Add a **v4 success-path catalog** as an amendment to the locked hint templates (`HINTS-ROAD-SIGNS` §7.11). Implement in `mcp_hints.py` only — no graph, ontology, or MCP shape changes.
31+
32+
### Design frame (extends v2, does not contradict it)
33+
34+
v2 (`propose/completed/HINTS-V2-PROPOSE.md` §1) ruled out **per-row** neighbors hints and confidence thresholds. v4 keeps both rules. Success-path hints are **output-level**, keyed on:
35+
36+
- echoed `requested_edge_types` + `requested_direction` (+ `subject_record` when already plumbed), and
37+
- the **homogeneous endpoint kind** of `results[].other.kind` (and `other.symbol_kind` when `kind == "symbol"`),
38+
39+
with **no** new graph reads and **no** per-edge-row emissions.
40+
41+
### Trigger contract (neighbors)
42+
43+
Fire a success-path hint iff **all** of:
44+
45+
1. `success is True` and `len(results) > 0` and `offset == 0` (same guard as v3 empty structural hints — paginated tail pages are ambiguous).
46+
2. `len(requested_edge_types) == 1` (single-edge calls only; multi-edge requests are agent-composed and out of scope).
47+
3. Every row’s `other.kind` (and method vs type `symbol_kind` when relevant) matches the row’s predicate — **mixed endpoint kinds → no hint** (lossy by design).
48+
4. Rendered string `len <= 120` after substitution; otherwise drop that row.
49+
50+
Priority: **`PRIORITY_LEAF_FOLLOWUP` (2)** — same tier as `describe` method leaf hints and route/client declaring-method rows. Fuzzy-strategy (`PRIORITY_META` 1) and v3 empty structural (`PRIORITY_META` 1) lose cap contests to success-path hints.
51+
52+
### Locked v4 template rows
53+
54+
Placeholders: `{id}` = echoed `origin_id` when a single origin is needed; `member_ids` / `client_ids` / `producer_ids` / `handler_ids` = conventional batch placeholders (same convention as v1 describe two-hop strings). No `{id}` substitution for batch placeholders — agents already treat them as “ids from the rows above.”
55+
56+
#### `neighbors` (highest priority — implement first)
57+
58+
| ID | Trigger | Template (verbatim target) |
59+
|---|---|---|
60+
| N1 | `requested_edge_types == ['DECLARES']`, `direction=='out'`, `subject_record` is type Symbol, all `other` are method/constructor Symbols | `members: neighbors(member_ids,'out',['DECLARES_CLIENT']) or neighbors(member_ids,'out',['EXPOSES'])` |
61+
| N2 | `['DECLARES_CLIENT']`, `direction=='out'`, all `other.kind=='client'` | `HTTP targets: neighbors(client_ids,'out',['HTTP_CALLS'])` |
62+
| N3 | `['DECLARES_PRODUCER']`, `direction=='out'`, all `other.kind=='producer'` | `async targets: neighbors(producer_ids,'out',['ASYNC_CALLS'])` |
63+
| N4 | `['EXPOSES']`, `direction=='in'`, all `other` are method/constructor Symbols | `callers: neighbors(handler_ids,'in',['CALLS'])` |
64+
| N5 | `['HTTP_CALLS']`, `direction=='in'`, all `other.kind=='client'` | `declaring method: neighbors(client_ids,'in',['DECLARES_CLIENT'])` |
65+
| N6 | `['ASYNC_CALLS']`, `direction=='in'`, all `other.kind=='producer'` | `declaring method: neighbors(producer_ids,'in',['DECLARES_PRODUCER'])` |
66+
67+
**Rejected from issue #163 (or deferred):**
68+
69+
| Candidate | Reason |
70+
|---|---|
71+
| Combined hint using “to see clients/routes…” | Violates v1 tone (“to see”); N1 uses imperative labels instead |
72+
| `neighbors(route_id,'in',['HTTP_CALLS'])` when results are clients | Covered by N5; symmetric async row is N6 |
73+
| Deriving strings from `EDGE_SCHEMA.typical_traversals` at success time | v3 owns mismatch recovery; success follow-ups are workflow-specific two-hop shapes, not `alien_subject` strings |
74+
| `IMPLEMENTS` / `EXTENDS` / `CALLS` success hints | Still deferred per v1 §5; add only with trace evidence in a later amendment |
75+
| Hints when `len(requested_edge_types) > 1` | Cap + ambiguity; agent chose a bundle deliberately |
76+
77+
**N1 note:** Unlike `describe` type rollups, neighbors success after `DECLARES` cannot branch on per-member `edge_summary` (not in the payload). N1 intentionally emits **one** combined clients/routes sign — same information density as the describe rollup pair, one cap slot.
78+
79+
#### `find` (second tranche)
80+
81+
| ID | Trigger | Template |
82+
|---|---|---|
83+
| F1 | `kind=='route'`, `len(results)>0`, not page-full | `handler: neighbors([route_id],'in',['EXPOSES'])` |
84+
| F2 | `kind=='client'`, `len(results)>0`, not page-full | `HTTP targets: neighbors([client_id],'out',['HTTP_CALLS'])` |
85+
| F3 | `kind=='producer'`, `len(results)>0`, not page-full | `async targets: neighbors([producer_id],'out',['ASYNC_CALLS'])` |
86+
87+
Use the **first** result’s `id` as `route_id` / `client_id` / `producer_id` when multiple rows are returned (output-level sign, not per-row). If `len(results) >= limit` and `has_more_results`, page-full meta (priority 1) still fires; F-rows use priority 2 and win the cap.
88+
89+
`describe(id=…)` cross-tool wording from #163 is **dropped** — `neighbors` alone reaches the handler; keeps one tool per hint.
90+
91+
#### `search` (optional third tranche — lowest priority)
92+
93+
| ID | Trigger | Template |
94+
|---|---|---|
95+
| S1 | `len(results)==1`, top hit `symbol_id` present | `inspect: describe(id='{symbol_id}')` |
96+
97+
**Do not** emit S1 on every multi-hit search (noise). If traces show agents stall on multi-hit pages, a follow-up amendment can add a dominant-score gate — not in v4 initial lock.
98+
99+
### Cap interaction
100+
101+
| Output | Typical success hint count | Competes with |
102+
|---|---|---|
103+
| `describe` | 0–3 (unchanged) | — |
104+
| `neighbors` | 0–1 success + 0–1 fuzzy | v3 empty (mutually exclusive with non-empty) |
105+
| `find` | 0–1 success | page-full meta (rare co-fire) |
106+
| `search` | 0–1 | weak-score meta (orthogonal triggers) |
107+
108+
No new priority level required. `PRIORITY_LEAF_FOLLOWUP` is sufficient.
109+
110+
### Module changes
111+
112+
- `mcp_hints.py`: add `TPL_*` constants + `neighbors_success_hints()` / `find_success_hints()` helpers; extend `generate_hints` branches.
113+
- Module header comment: point to this propose as v4 amendment.
114+
- `MCP_HINTS_FIELD_DESCRIPTION`: no change (behavior stays advisory).
115+
116+
## Scope
117+
118+
- v4 template catalog and generator logic in `mcp_hints.py`
119+
- Unit tests in `tests/test_mcp_hints.py` (synthetic payloads +, where cheap, `neighbors_v2` round-trips on `kuzu_graph`)
120+
- Appendix amendment note in `propose/completed/HINTS-ROAD-SIGNS-PROPOSE.md` (traceability paragraph only — optional docs PR)
121+
122+
## Schema / Ontology / Re-index impact
123+
124+
- Ontology bump: **not required**
125+
- Re-index required: **no** (hints are pure functions of MCP payloads)
126+
- Config/tool surface changes: **none** (field `hints` already exists)
127+
128+
## Tests / Validation
129+
130+
Named scenarios (implementer contract):
131+
132+
| Scenario | Assert |
133+
|---|---|
134+
| `test_hints_neighbors_declares_methods_emits_member_followup` | N1 fires on type + `DECLARES` + method targets |
135+
| `test_hints_neighbors_declares_client_homogeneous_emits_http_calls` | N2 |
136+
| `test_hints_neighbors_declares_producer_homogeneous_emits_async_calls` | N3 |
137+
| `test_hints_neighbors_exposes_in_methods_emits_calls` | N4 |
138+
| `test_hints_neighbors_http_calls_in_clients_emits_declares_client` | N5 |
139+
| `test_hints_neighbors_mixed_endpoint_kinds_silent` | client + route in one page → `[]` success-path |
140+
| `test_hints_neighbors_success_beats_fuzzy_in_cap` | constructed payload with both signals → leaf hint retained |
141+
| `test_hints_find_route_success_emits_handler` | F1 |
142+
| `test_hints_find_client_success_emits_http_calls` | F2 |
143+
| `test_hints_search_single_hit_emits_describe` | S1 |
144+
| `test_hints_all_v4_templates_under_120_chars` | rendered with realistic ids |
145+
| Char-cap + dedupe + cap-5 | reuse existing `finalize_hint_list` tests pattern |
146+
147+
## Open Questions ([TBD])
148+
149+
1. **Single-edge-only gate** — Recommended: **yes** for v4 (row 2 in trigger contract). Multi-edge `neighbors` calls are advanced composition; guessing follow-ups is likely wrong.
150+
2. **Emit N1 when some members lack clients/routes** — Recommended: **yes, always** when N1’s homogeneous method predicate holds. Lossy sign beats silence; agent may ignore.
151+
3. **Search S1 in initial PR** — Recommended: **defer to PR-B** (or skip if scope pressure). Neighbors tranche delivers most of #163’s value.
152+
4. **`find` F1 when `len(results) > 1`** — Recommended: **emit once** using first id; matches output-level rule. Mention in PR description so reviewers do not expect per-row hints.
153+
5. **Amend `HINTS-ROAD-SIGNS` appendix in-repo** — Recommended: **yes**, short “v4 amendment (#163)” paragraph like the #161 producer block.
154+
155+
## Out of scope
156+
157+
- Per-row hints on `Edge` / `SearchHit` / `NodeRef`
158+
- `IMPLEMENTS` / `EXTENDS` / generic `CALLS` success chains (v1 §5 deferral stands until trace-backed)
159+
- `describe` catalog changes (covered by #161 / existing v1)
160+
- `resolve(status='one')` hints
161+
- Structured `next_actions` / pre-fetched walks
162+
- Graph or `EDGE_SCHEMA` changes (no `success_follow_up` field on `EdgeSpec` in v4)
163+
- Hint versioning field (`hints_version`)
164+
- Conditioning on `attrs.match` / confidence for `HTTP_CALLS` / `ASYNC_CALLS` rows (strategy already covered by v2 fuzzy hint on non-empty neighbor pages)
165+
166+
## Sequencing / Follow-ups
167+
168+
Suggested **2 PRs** (can collapse to 1 if reviewer prefers):
169+
170+
| PR | Delivers | Depends on |
171+
|---|---|---|
172+
| **PR-A** | N1–N6 + neighbors tests + char-cap sweep for new templates | — |
173+
| **PR-B** | F1–F3, optional S1 + find/search tests + appendix traceability note | PR-A optional |
174+
175+
After land: move this file to `propose/completed/`, add `plans/PLAN-HINTS-V4.md` + `CURSOR-PROMPTS-HINTS-V4.md` if the team wants the per-PR sentinel contract (not required for a 1–2 PR effort).
176+
177+
**Related issues:** #161 (describe producer symmetry — landed); #163 (this propose). No ontology coordination with SCHEMA-V2.
178+
179+
## Grill notes (issue #163 review)
180+
181+
What the issue gets right:
182+
183+
- Problem is real and measurable (empty `hints` on happy paths).
184+
- Correctly cites v1 deferral of `HTTP_CALLS` / `ASYNC_CALLS` chains now that ontology 14 + Client/Producer endpoints exist.
185+
- Identifies `neighbors` as the highest-impact gap vs already-strong `describe`.
186+
- Purity constraint (payload-only) is preserved.
187+
188+
What needed correction in the issue draft:
189+
190+
| Issue draft element | v4 decision |
191+
|---|---|
192+
| Wording “to see clients/routes…” | Replaced with imperative labels (`members:`, `HTTP targets:`) per HINTS-ROAD-SIGNS §8 |
193+
| `find` → `describe(id=…)` OR `neighbors` | `neighbors` only (one tool per hint) |
194+
| `search` hint on any top hit with `symbol_id` | Gated to `len(results)==1` to avoid spam |
195+
| Unconditional success hints without homogeneous kind check | Required — mixed `other.kind` → silent |
196+
| New priority tier | Unnecessary — reuse `PRIORITY_LEAF_FOLLOWUP` |
197+
| Imply re-index / schema work | None needed |
198+
199+
**Tension with HINTS-V2 §1 (“not what to do next”)**: v4 resolves by classifying these as **continuation signs** grounded in `(edge requested, endpoint kind returned)` — the same observable contract as “you got client nodes” fuzzy strategy, but pointing forward along the resolver chain instead of backward at attrs.

0 commit comments

Comments
 (0)