propose: v4 success-path hints (issue #163)

[HumanBean17]

What

Adds propose/HINTS-V4-SUCCESS-PATH-PROPOSE.md — design for success-path hints on neighbors, find, and optional search.

Why now

Real-codebase testing (#163) shows most successful tool calls return empty hints; recovery-path hints are well covered but happy-path workflow chains (class → members → clients → HTTP_CALLS) are not.

Highlights

• Locks six neighbors templates (DECLARES→members, client→HTTP_CALLS, producer→ASYNC_CALLS, handler→CALLS, reverse resolution)
• Locks three find success templates; defers noisy multi-hit search hint to optional tranche
• Homogeneous other.kind gate, single-edge-only triggers, PRIORITY_LEAF_FOLLOWUP — no ontology bump
• Explicit rejections from hints: expand success-path hint catalog — most tool invocations return empty hints #163 draft (tone, dual-tool hints, per-row hints)
• Suggested 2-PR implementation split (neighbors first)

Tests

Docs-only; baseline unchanged.

Out of scope

• Implementation in mcp_hints.py (follow-up PRs after propose approval)
• IMPLEMENTS / EXTENDS / generic CALLS success chains
• Graph or ontology changes

Made with Cursor

[HumanBean17]

Critical Review: v4 success-path hints propose

The propose is well-structured, clearly motivated, and properly aligned with the existing hints framework (v1/v2/v3). It correctly identifies a real gap: most successful tool invocations return empty hints. The writing is disciplined and follows the tone of the existing proposes. That said, several issues worth flagging.

Issues

1. N1 trigger has an implicit subject_record dependency that isn't fully specified

N1 fires when requested_edge_types == ['DECLARES'], direction=='out', and "subject_record is type Symbol." The trigger contract says "echoed requested_edge_types + requested_direction (+ subject_record when already plumbed)" — the parenthetical is vague. The payload does already plumb subject_record (line ~1406 in mcp_v2.py), but an implementer could miss this. Make the dependency explicit in the trigger contract rather than deferring to "when already plumbed."

2. The homogeneous other.kind gate needs definition of what other is

The propose references results[].other.kind and results[].other.symbol_kind, but generate_hints works on a dict[str, Any] payload (serialized via .model_dump()). The propose never spells out the serialized shape the generator reads. An implementer needs to know they're reading payload["results"][i]["other"]["kind"]. This should be explicit.

3. N4 (EXPOSES inbound) may be too noisy on typical codebases

After an agent finds route handlers via neighbors(route_id, 'in', ['EXPOSES']), recommending neighbors(handler_ids,'in',['CALLS']) is plausible but could be noisy: many controller methods have zero inbound CALLS (they're entry points). The agent could waste a call on a dead-end. This isn't discussed in the "Rejected" table or open questions. Consider a gating condition or at least an explicit acknowledgment of the noise risk.

4. N5/N6 reverse resolution hints overlap with existing describe hints

If an agent calls neighbors(route_id, 'in', ['HTTP_CALLS']) and gets client nodes, N5 suggests neighbors(client_ids,'in',['DECLARES_CLIENT']). But describe(client_id) already emits TPL_DESCRIBE_CLIENT_DECLARING with the same call shape. The v4 N5 hint is partially redundant. The propose should acknowledge this overlap and justify why a duplicate signal on the neighbors tool is still worth the cap slot.

5. F1/F2/F3 — placeholder vs actual id substitution is ambiguous

The propose says "Use the first result's id as route_id" but the template column shows neighbors([route_id],'in',['EXPOSES']) — a symbolic placeholder. The existing v1 convention is that member_ids / overrider_ids are not substituted (batch placeholders). F1-F3 claim actual substitution from the first result, which contradicts the batch-placeholder convention. Make this explicit: are these substituted with the real id or kept as symbolic names?

6. Open question 1 contradicts the trigger contract

The trigger contract (item 2) already locks len(requested_edge_types) == 1. Then open question 1 asks whether to use a single-edge-only gate, recommending "yes." These contradict — if the trigger contract is locked, the question is answered. Clean up.

7. N1 is a dual-tool recommendation despite v1 frame §2.1

N1 renders as: members: neighbors(member_ids,'out',['DECLARES_CLIENT']) or neighbors(member_ids,'out',['EXPOSES']). This contains two call shapes joined by "or." The v1 frame (§2.1) says a hint "references one next call." The rejected table says combined "to see clients/routes…" wording was rejected for tone — but N1 is a combined hint. There's a reasonable defense (one sign pointing at two exits), but the propose should state it explicitly rather than leave it as an unaddressed tension with §2.1.

8. Missing test scenario for offset > 0 suppression on non-empty results

The trigger contract requires offset == 0. The test table should include a negative case for success hints suppressed on a paginated tail page (offset > 0, non-empty results). v3 has this pattern already.

9. S1 is listed as "locked" but also "optional third tranche" — mixed signal

If S1 is deferred, it shouldn't appear in the locked template table. Either lock it or move it to a "deferred candidates" section.

10. No cap interaction walkthrough for success + fuzzy co-fire

What if a neighbors result has non-empty results (triggering a v4 success hint at PRIORITY_LEAF_FOLLOWUP=2) AND carries fuzzy-strategy edges (triggering the v2 hint at PRIORITY_META=1)? The success hint wins by priority — but this interaction isn't explicitly walked through. Add a row to the cap interaction table.

Minor nits

• The "Grill notes" section reads more like a review memo than propose content. Consider moving to PR description or dropping.
• Should MCP_HINTS_FIELD_DESCRIPTION note success-path behavior (e.g., "success hints describe first-page results only")?

What it gets right

• Correctly identifies neighbors as the highest-impact gap.
• Homogeneous other.kind gate is disciplined — avoids noisy mixed-kind emissions.
• Reuses PRIORITY_LEAF_FOLLOWUP instead of inventing a new tier.
• 2-PR split (neighbors first, find second) is pragmatic.
• Explicit rejection table is strong and well-reasoned.
• No ontology bump, no re-index, no graph changes — pure mcp_hints.py scope. Clean.