Pre-computed aggregates and question-shaped commands

[apgiorgi]

Part of the Agentic UX spec series. See sibling issues for related buckets.

Motivation

The single biggest token cost in agentic workflows is the round-trip chain: list → filter → get → summarize. Every step round-trips through the agent's context window. The fix is to give agents purpose-built endpoints that answer the question directly, and to embed common aggregates in list responses so they don't need a second call to know "how many" or "what's worst."

This is the single highest-impact UX shift in this series, but it depends on #9 (output format) and #12 (error contract) being settled first.

Spec

Inline aggregates on list operations

Every list returns a top-level envelope with pre-computed aggregates:

{
  "count": 142,
  "truncated": false,
  "aggregates": { "by_severity": {...}, "total_cost_usd": 12345.67 },
  "results": [...]
}

This kills the "call list, then call count, then call sum" chain.

Question-shaped subcommands

Concrete examples to seed the conversation — exact verbs TBD with product:

• dci anomalies recent — anomalies since last invocation/window, ranked
• dci anomalies explain <id> — one call returns context + likely cause + linked resources
• dci budgets at-risk — budgets projected to breach in the next N days
• dci costs explain --service X --window 7d — what changed and why
• dci ask "..." — natural-language frontend that dispatches to the right verb (stretch goal; depends on DCI API capability)

Each verb collapses what would today be 3–5 separate calls into one.

Principles

• Verbs are noun + question, not CRUD
• Outputs are self-contained: no "now call X to get Y" required for the common case
• Default output is compact (Token-efficient output format #9), with --explain / --verbose to opt into details

References

• axi.md — principle 4 (pre-computed aggregates eliminate round trips): https://axi.md/
• Grafana gcx CLI — question-shaped workflows like "why did this endpoint get slower?": https://grafana.com/blog/get-observability-in-the-terminal-for-you-and-your-agents-with-the-gcx-cli-tool/

Open questions

• Which questions do customers actually ask agents about DCI? (Pull from telemetry + Zendesk if possible.)
• Should aggregates be opt-in (--aggregate by:severity) or always-on?
• How do we keep this surface from sprawling? Suggest: a written rubric for what earns a question-shaped verb.

Dependencies

• Blocked by Token-efficient output format #9 (output format / envelope shape)
• Blocked by Stable exit codes, structured errors, idempotency #12 (error envelope shape)

Acceptance criteria

• List operations return count, truncated, and at least one domain-relevant aggregates block
• At least 3 question-shaped verbs shipped (e.g. anomalies recent, budgets at-risk, costs explain)
• Rubric documented for what qualifies as a question-shaped verb (to control surface growth)