plan: DESCRIBE-HINTS-STRUCTURAL — type wiring and method-body road signs

[HumanBean17]

Summary

• Add implementation plan + agent prompt for 10 new describe success-path hint rows (A–E, G–J) reading edge_summary in/out counts and record.data
• Single PR scope: helpers (_in_count, _type_rollup_would_emit), 7 new TPL_DESCRIBE_* constants, is_type control-flow refactor, all 10 rows with string + structured parity
• No ontology bump, no re-index, no mcp_v2.py / server.py changes

Plan

• plans/PLAN-DESCRIBE-HINTS-STRUCTURAL.md
• plans/AGENT-PROMPTS-DESCRIBE-HINTS-STRUCTURAL.md

Propose

• propose/DESCRIBE-HINTS-STRUCTURAL-PROPOSE.md
• Tracks tier 3 (deferred): #191

Test plan

• Plan reviewed and approved
• Implementation PR follows with 21 named tests

🤖 Generated with Claude Code

[HumanBean17]

PR #213 Review: plan: DESCRIBE-HINTS-STRUCTURAL — type wiring and method-body road signs

Overview

Planning PR — two documents preparing for 10 new describe success-path hint rows (A–E, G–J). No production code changes.

Strengths

• Exceptionally thorough. Every row specified with exact gate conditions, template strings, structured-hint args, and priority levels. Step-by-step implementation order (helpers → constants → refactor → rows → tests) minimizes risk.
• Consistent with existing patterns. _in_count mirrors _out_count, new templates follow TPL_DESCRIBE_* naming, all new rows use PRIORITY_LEAF_FOLLOWUP. Dual-list pattern preserved throughout.
• Well-scoped. Out-of-scope list is explicit (no ontology bump, no re-index, no mcp_v2.py/server.py changes, tier 3 deferred to Describe hints tier 3: callers, members, EXTENDS (gated) #191). Sentinel checks are a nice touch.
• Good risk assessment. is_type early-return removal correctly identified as high severity with prescribed immediate test run.

Issues

1. Test count ambiguity (minor)

Test #7 (test_hints_describe_method_outbound_calls_low_fanout_non_other_emits) is labeled "(optional)" in the agent prompt, but the PR body, plan, and definition of done all say "21 named tests." If genuinely optional, update the count to "20–21." If required, drop "(optional)" to avoid ambiguity for the implementing agent.

2. is_type refactor — fallthrough guard (observation)

After removing the early return, the new return at the bottom of is_type fires even if no rollup or tier-1 hints were appended. An is_type node with no edges returns empty instead of falling through. Looking at the current code, the is_type block is the last conditional before the function's final fallback, so this is not a regression — just worth the implementing agent being aware.

3. Row C role == "SERVICE" only (observation)

@Component/@Repository classes with INJECTS.out > 0 won't get the dependencies hint. Appears intentional and tracked as tier 3 per #191. Flagging for awareness.

Verdict

Approve. Clean, well-structured plan following the project's propose-then-implement culture. One actionable item: resolve the optional/required ambiguity on test #7.