📋 Phase 7 — Post-MVP Roadmap (tracking)

[pedrosakuma]

Phase 7 — Post-MVP Roadmap

This issue tracks all post-MVP work. The MVP (Phases 1–6) is complete: 9 diagnostic tools functional, end-to-end validated locally via Docker sidecar, samples in place to exercise the LLM diagnostic loop.

Phase 7 organizes the next wave of work around four themes, with explicit dependencies so we can pick the highest-leverage item that is ready.

📚 Research artifacts driving Phase 7

Two deep-research documents (kept in the session workspace; key findings inlined in each sub-issue):

• MCP best practices & spec catch-up — surveyed spec 2025-11-25 + draft, ~100 MCP clients (Claude Desktop, Cursor, Copilot CLI, Cline, Continue, VS Code MCP, …) and top reference servers (GitHub MCP, Honeycomb, Datadog, fast-agent, mcpc, goose). Drives the spec-compliance and discoverability issues.
• .NET runtime troubleshooting methodology — consolidates USE / RED / Golden Signals, dotnet-monitor collection rules, Brendan Gregg, Datadog compare_profiles into a 10-scenario decision tree. Confirms start_investigation is novel — no consulted platform returns an InvestigationPlan artifact. Drives the drilldown issues.

---

🔧 Spec catch-up

Cheap baseline so everything else lines up with the current spec.

• chore(spec): bump protocolVersion to 2025-11-25 and audit changes #1 spec-bump — bump protocolVersion to 2025-11-25 and audit
• chore(discoverability): serverInfo.description + Title on every tool #2 server-info-instructions — serverInfo.description + tool Title
• feat(spec): outputSchema + structuredContent on collect_* tools #3 output-schema — outputSchema + structuredContent
• feat(spec): support experimental Tasks for long-running collects #4 tasks-support — experimental Tasks for long-running collects
• feat(spec): elicitation with graceful degradation #5 elicit-graceful — elicitation with graceful degradation

🧭 Discoverability & ergonomics

Make the surface a low-context LLM can actually use well.

• feat(discoverability): summary + hints + structured errors + annotations #6 mcp-discoverability — summary + hints + structured errors + annotations
• feat(discoverability): MCP Prompts for common investigations #7 mcp-prompts — server-side Prompts for common investigations

🔬 Drill-down architecture (token efficiency)

The thing that turns this from "a bag of tools" into a guided experience.

• feat(drilldown): handle + summary + detail tools (token-efficient drill-down) #8 mcp-drilldown — handle + summary + detail tools
• feat(drilldown): start_investigation meta-tool (cold/warm/hypothesis plans) #9 start-investigation — meta-tool with cold/warm/hypothesis plans
• feat(drilldown): portable investigation summaries with provenance + lineage #10 investigation-memory — portable summaries with provenance + lineage

🩺 Advanced diagnostics

• feat(diagnostics): source-level resolution for cpu samples (TraceLog + SourceLink) #11 source-resolution — source-level resolution for CPU samples (TraceLog + SourceLink)
• feat(diagnostics): rich dump inspection via ClrMD #12 clrmd-dump-inspection — rich dump inspection via ClrMD
• feat(diagnostics): NativeAOT CPU sampling fallback (perf/ETW) #13 nativeaot-fallback — NativeAOT CPU sampling fallback (perf / ETW)
• design: handoff contract with assembly-inspector MCP (MethodIdentity) #18 handoff-contract — MethodIdentity handoff with companion dotnet-assembly-mcp

🏗️ Infrastructure

• chore(infra): publish MCP server as NativeAOT #14 aot-publish-server — publish MCP server as NativeAOT
• feat(infra): central K8s topology (no per-pod sidecar) #15 central-k8s — central K8s topology (no per-pod sidecar)
• feat(infra): cloud platform integrations (App Service / ACA / ECS / Lambda) #16 cloud-integrations — App Service / ACA / ECS / Lambda

🤝 Companion projects

• pedrosakuma/dotnet-assembly-mcp — static navigation of .NET assemblies (types, methods, decompilation). Token-efficient complement to source resolution. Handoff designed in design: handoff contract with assembly-inspector MCP (MethodIdentity) #18.

---

🧩 Dependency graph

#1 spec-bump ──────────┬─→ #3 output-schema ───┐
                       │            │          ↓
                       │            └→ #18 handoff-contract
                       └→ #6 mcp-discoverability ──┬─→ #8 mcp-drilldown ──┬─→ #11 source-resolution ─┐
#2 server-info-instr ─────↑                        │                      │                          │
                                                   └→ #7 mcp-prompts ─────┤                          │
                                                                          ↓                          │
                                                                  #9 start-investigation ────────────┤
                                                                                                     ↓
                                                                                          #10 investigation-memory

independent (no dependency yet):
#4 tasks-support       #5 elicit-graceful
#12 clrmd-dump-inspection   #13 nativeaot-fallback
#14 aot-publish-server      #15 central-k8s           #16 cloud-integrations

▶️ Suggested execution order

The cheap roots first; the longer chain only after the spec baseline is in.

1. chore(spec): bump protocolVersion to 2025-11-25 and audit changes #1 spec-bump + chore(discoverability): serverInfo.description + Title on every tool #2 server-info-instructions (parallel, both cheap)
2. feat(discoverability): summary + hints + structured errors + annotations #6 mcp-discoverability + feat(spec): outputSchema + structuredContent on collect_* tools #3 output-schema (parallel)
3. design: handoff contract with assembly-inspector MCP (MethodIdentity) #18 handoff-contract (lands with feat(spec): outputSchema + structuredContent on collect_* tools #3 — defines the MethodIdentity shape that goes into the structured output)
4. feat(drilldown): handle + summary + detail tools (token-efficient drill-down) #8 mcp-drilldown — biggest single architectural change
5. feat(discoverability): MCP Prompts for common investigations #7 mcp-prompts (after feat(discoverability): summary + hints + structured errors + annotations #6)
6. feat(diagnostics): source-level resolution for cpu samples (TraceLog + SourceLink) #11 source-resolution (after feat(drilldown): handle + summary + detail tools (token-efficient drill-down) #8)
7. feat(drilldown): start_investigation meta-tool (cold/warm/hypothesis plans) #9 start-investigation (after feat(discoverability): MCP Prompts for common investigations #7 + feat(drilldown): handle + summary + detail tools (token-efficient drill-down) #8)
8. feat(drilldown): portable investigation summaries with provenance + lineage #10 investigation-memory (after feat(drilldown): start_investigation meta-tool (cold/warm/hypothesis plans) #9 + feat(diagnostics): source-level resolution for cpu samples (TraceLog + SourceLink) #11)
9. feat(spec): support experimental Tasks for long-running collects #4 tasks-support / feat(spec): elicitation with graceful degradation #5 elicit-graceful whenever SDK helpers land
10. Long-term: feat(diagnostics): rich dump inspection via ClrMD #12 / feat(diagnostics): NativeAOT CPU sampling fallback (perf/ETW) #13 / chore(infra): publish MCP server as NativeAOT #14 / feat(infra): central K8s topology (no per-pod sidecar) #15 / feat(infra): cloud platform integrations (App Service / ACA / ECS / Lambda) #16

---

🤝 Issues are intentionally small and dependency-aware — comment on any of them to discuss scope, or open a PR linking to its issue.

[pedrosakuma]

Update 2026-05-19 — ClrMD value-extraction waves

Live dogfooding (heap dump + new inspect_live_heap tool committed in 7187552) surfaced that we're using ~20% of what ClrMD can deliver. Opened 3 sequential waves to close the gap:

• design: unified heap snapshot store + drilldown queries (wave 1) #24 wave 1 — Unified heap snapshot store + drilldown queries (retention/roots/finalizer/fragmentation). Establishes the split collector, unified drilldown pattern.
• feat(diagnostics): thread + lock graph snapshot (wave 2) #25 wave 2 — Thread + lock graph snapshot (deadlock detection, contention diagnosis). Depends on design: unified heap snapshot store + drilldown queries (wave 1) #24 for the store pattern.
• feat(diagnostics): static-field & delegate-target leak detection (wave 3) #26 wave 3 — Static-field & delegate-target leak detection. Depends on design: unified heap snapshot store + drilldown queries (wave 1) #24; lowest priority.

All three are research-backed by the in-session design discussion: shippable as Resources (drilldown queries) rather than new tools to preserve the ≤ 10 tools/context ceiling — except wave 2's collect_thread_snapshot which intentionally pushes to 11 tools because deadlock diagnosis is the largest current gap.

Recent stabilization commits unblocking these waves:

• 4301c97 fix(schema): InvestigationProvenance optional fields
• 7187552 feat(server): inspect_live_heap tool + dump schema fixes
• f9987e5 chore(sample): pathology endpoints for demos

[pedrosakuma]

Phase 7 — fechamento

Todos os sub-itens do roadmap foram entregues. Wave final (spikes de design) consolidada nos PRs:

Item	PR	Descrição
#14 aot-publish-server	—	Re-validado: bloqueado por 3 deps upstream (TraceEvent 3.2.2, ModelContextProtocol 1.3.0, MVC cascade). Fechado not planned; tracker técnico segue em #19.
#15 central-k8s	#137	docs/central-k8s-design.md — recomenda orchestrator namespace-scoped + ephemeral debug container por investigação.
#16 cloud-integrations	#138	docs/cloud-integrations-design.md — recomenda AWS ECS/Fargate como primeiro target.
#20 central-orchestrator	#139	docs/central-orchestrator-design.md — tool surface (list_pods / attach_to_pod / …), RBAC, threat model, fases.
#22 cloud-recipes	#140	docs/cloud-recipes-design.md — ECS/Fargate primeiro, depois Cloud Run (com caveat gVisor/ptrace).

A continuação (próximas ondas, candidate themes) está rastreada em #23.

Fechando este meta como completed.

[pedrosakuma]

Adding #279 (Native allocation sampler over the perf backend) as a Phase 7 completeness item.

Surfaced while auditing allocation/leak investigation completeness. Re-evaluated the two previously-suspected gaps:

• allocation -> GC-root linkage — not a gap. Achievable today via query_snapshot(view="diff") intersect allocation-sample top types, then gcroot. At most needs a NextActionHint nudge.
• native (unmanaged) allocation attribution — tracked in Native (unmanaged) allocation sampler over the perf backend #279. We can already detect/classify native growth (sample_memory_trend RSS/Anonymous + gc-heap-size triangulation, ~2 steps); the missing piece is attributing it to a call site. Fits cleanly on the existing perf backend (same pattern as off-CPU / NativeAOT CPU sampling), so it is not an architectural gap — just unbuilt. The only non-trivial sub-piece is alloc/free matching for true retention vs hotspot-only.

Depends on / relates to the perf-backed sampler infra already shipped.

[pedrosakuma]

Adding #280 (Discoverability: LLM does not reach for the tools in an obvious performance scenario) as a Phase 7 discoverability item.

Distinct from capability work — surfaced while auditing allocation/leak ergonomics. Observed with Copilot CLI: in a clearly performance-shaped scenario the model fell back to generic advice instead of calling collect_events / inspect_process.

Root cause is the entry point, not the capability: the real playbooks live in pull-only channels (Prompts are never auto-invoked; Resources read only on demand), so the only reliable push surface is per-tool [Description] plus ServerInstructions if the client injects it. Tool names are mechanism-oriented (collect_events, collect_sample) and do not match intent phrasing ("app is slow").

First task is verifying what Copilot CLI does with ServerInstructions / Prompts; then strengthen intent-level lexical triggers and titles on the entry-point tools (inspect_process, start_investigation), keeping within the tool-count budget.

[pedrosakuma]

Spun out a capability-gap review against adityamandaleeka/pvanalyze (offline .nettrace analyzer) into three tiers:

• CPU drilldown: topMethods / group-by / hot-path / caller-callee views (pvanalyze parity) #313 — Tier 1 CPU drilldown views (topMethods / group-by / hot-path / caller-callee) — reuses the existing CpuSampleTraceArtifact, no new collection. Starting implementation now.
• Richer GC views (timeline/longest/byGeneration) + generic events catalog (pvanalyze parity) #314 — Tier 2 richer GC views + generic events catalog.
• DATAS analysis: heap-count tuning / TCP / MSL / gen2 backstop (pvanalyze parity) #315 — Tier 3 DATAS analysis (heap-count tuning / TCP / MSL / gen2 backstop) — strategic, larger effort.

Not adopting (for now): SpeedScope export and offline .nettrace-from-disk analysis.