feat(help): address madt_help by action, not only by whole tool #754

New issue

Open

opened 2026-10-13 16:59:00 +00:00 by hexajon · 0 comments

hexajon commented

2026-10-13 16:59:00 +00:00

Owner

What happens

madt_help is topic-dispatched, one topic per tool: topic="issues", topic="finish", topic="adr". That is already per-tool. But a fat action-dispatched tool makes one topic large. The issues topic runs about 600 lines, because madt_issues has around 40 actions (ADR 0015). To confirm one action's params, such as comment (number and body), I read the whole topic.

Why it matters

Even after #716 puts the params in the schema, help stays the fallback for a non-obvious flag or an unfamiliar action. A 600-line read for one action's params is a large context cost for a small question, and it repeats every session. Smaller, scoped help is the cheaper default.

Proposal

Let madt_help address a single action or a small slice, not only a whole tool.

A per-action lookup, such as topic="issues" action="comment" or topic="issues.comment", returns only that action's summary, its required params, and one example.
A tool topic with no action returns a short index: the one-line purpose, then the action list with each action's required params, and a pointer to fetch one action for the detail. It does not inline every action's full prose.
ADR 0008 makes the operation registry the source of record, and it already renders action and op summaries. Generate the per-action help from that registry, so the help cannot drift from the schema.

Relation to #716

A distinct axis. #716 makes the schema self-sufficient, so the help is not needed. This makes the help cheap to read when it still is. Both cut the same cost: a wasted round-trip, or a large read for a small question.

## What happens `madt_help` is topic-dispatched, one topic per tool: `topic="issues"`, `topic="finish"`, `topic="adr"`. That is already per-tool. But a fat action-dispatched tool makes one topic large. The `issues` topic runs about 600 lines, because `madt_issues` has around 40 actions (ADR 0015). To confirm one action's params, such as `comment` (number and body), I read the whole topic. ## Why it matters Even after #716 puts the params in the schema, help stays the fallback for a non-obvious flag or an unfamiliar action. A 600-line read for one action's params is a large context cost for a small question, and it repeats every session. Smaller, scoped help is the cheaper default. ## Proposal Let `madt_help` address a single action or a small slice, not only a whole tool. - A per-action lookup, such as `topic="issues" action="comment"` or `topic="issues.comment"`, returns only that action's summary, its required params, and one example. - A tool topic with no action returns a short index: the one-line purpose, then the action list with each action's required params, and a pointer to fetch one action for the detail. It does not inline every action's full prose. - ADR 0008 makes the operation registry the source of record, and it already renders action and op summaries. Generate the per-action help from that registry, so the help cannot drift from the schema. ## Relation to #716 A distinct axis. #716 makes the schema self-sufficient, so the help is not needed. This makes the help cheap to read when it still is. Both cut the same cost: a wasted round-trip, or a large read for a small question.

hexajon referenced this issue

2026-10-20 16:50:51 +00:00

fix(help): the top-level "--help" hides commands behind a truncated list #844

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

sixfold-space/madtea#754

No description provided.

Rows
Columns