Content-first output and contextual disclosure

[apgiorgi]

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

Motivation

Agents skim and humans scan. Both lose if the first thing they see is help text, marketing, or a wall of "next steps" that they didn't ask for. axi.md principles 8–10 codify this: lead with the data; then hint; let the agent ask for help on demand.

Spec

Content first

• The first bytes of stdout are the requested data (or an empty-state envelope per Stable exit codes, structured errors, idempotency #12)
• No banners, no "Welcome to DCI" lines, no version footers
• Marketing/upgrade nags route to stderr (or are gated behind --check-update)

Contextual disclosure (next-step hints)

• Hints ("You can drill into this with dci anomalies explain <id>") appear after the result, on stderr
• Hints are off by default in agent mode; on by default for humans
• Per-result hints are scoped to what the user actually did, not a generic dump

Concise per-subcommand help

• dci <cmd> --help is terse: one-line description, flags, one example, link to longer docs
• A separate dci <cmd> --help-full (or similar) for the wall of text
• Avoid embedding tutorial-length copy in --help — it bloats agent context every time they read it

References

• axi.md — principles 8 (content first), 9 (contextual disclosure), 10 (consistent help): https://axi.md/
• "Be brief" benchmark: https://www.maxtaylor.me/articles/i-benchmarked-caveman-against-two-words

Open questions

• Do we need a way for humans to opt into verbose help globally (DCI_VERBOSE_HELP=1)?
• Where do hints come from — hand-written per command, or derived from a manifest?

Acceptance criteria

• No banners, marketing, or upgrade nags on stdout
• Next-step hints on stderr only, suppressed in agent mode
• --help per subcommand fits in <30 lines; longer docs behind --help-full or a docs URL