naming: make madt_commits and madt_stats distinct from madt_commit and madt_status #690

New issue

Open

opened 2026-10-02 20:13:30 +00:00 by hexajon · 1 comment

hexajon commented

2026-10-02 20:13:30 +00:00

Owner

Problem

Two pairs of madtea commands differ by one letter, and each pair does different work:

Name	What it does	Plane
`commit` / `madt_commit`	Stages files and makes a `git commit`	local checkout
`commits` / `madt_commits`	Lists, gets, diffs, and compares commits through the forge API, plus CI statuses	forge
`status` / `madt_status`	Working-tree status: branch, ahead/behind, staged and unstaged files	local checkout
`stats` / `madt_stats`	Repo, org, contributor, and issue statistics	forge

A one-letter typo selects the wrong plane. madt_commit writes; madt_commits only reads. In a tool list, the pairs sit next to each other and look the same.

What gh and tea do

Neither one gives a name to copy:

gh has no commit, commits, or stats command. gh reads commits with gh search commits. gh status exists, but it is a dashboard of assigned issues, PRs, review requests, and mentions across repos, not working-tree status (https://cli.github.com/manual/gh_status).
tea has none of the four names (https://gitea.com/gitea/tea/src/branch/main/docs/CLI.md).

docs/COMPARISON.md agrees: gh and tea are ❌ on the commits, stats, status, and commit rows.

The naming rules that apply

docs/contributing/naming-conventions.md:62-84 gives the singular name to the local git wrapper and the tea-canonical plural to the forge resource. That rule produced commit vs commits. The same section records one exception: the forge branch resource is branches-remote, not branches, because branch vs branches "reads as tea jargon and confuses non-tea users". commit vs commits has the same problem.

status mirrors git status, and a local wrapper matches git exactly, so status keeps its name. stats has no gh or tea equivalent, so rule 3 of the convention applies: pick a clear name.

Candidate names

I have not picked the names yet.

commits / madt_commits: commits-remote / madt_commits_remote. This follows the branches-remote precedent, so it is a second recorded exception to ADR 0016.
stats / madt_stats: insights / madt_insights (the name GitHub's web UI gives to the same data), or analytics / madt_analytics.

Acceptance criteria

The CLI command and the MCP tool use the new name on both surfaces. No alias stays behind (naming-conventions.md bans aliases).
stats usage moves with the rest of stats.
ADR 0016 records the commits exception next to the branches-remote one, and the naming-conventions.md table gains its row.
The parity test in internal/parity/ passes on the new names.
endpointSuggestions in internal/service/api/suggestions.go, docs/COMPARISON.md, the help topics, the server instructions, and the generated reference docs use the new names.
Every tool description that names madt_commits or madt_stats uses the new name.

## Problem Two pairs of madtea commands differ by one letter, and each pair does different work: | Name | What it does | Plane | |---|---|---| | `commit` / `madt_commit` | Stages files and makes a `git commit` | local checkout | | `commits` / `madt_commits` | Lists, gets, diffs, and compares commits through the forge API, plus CI statuses | forge | | `status` / `madt_status` | Working-tree status: branch, ahead/behind, staged and unstaged files | local checkout | | `stats` / `madt_stats` | Repo, org, contributor, and issue statistics | forge | A one-letter typo selects the wrong plane. `madt_commit` writes; `madt_commits` only reads. In a tool list, the pairs sit next to each other and look the same. ## What gh and tea do Neither one gives a name to copy: - gh has no `commit`, `commits`, or `stats` command. gh reads commits with `gh search commits`. `gh status` exists, but it is a dashboard of assigned issues, PRs, review requests, and mentions across repos, not working-tree status (https://cli.github.com/manual/gh_status). - tea has none of the four names (https://gitea.com/gitea/tea/src/branch/main/docs/CLI.md). `docs/COMPARISON.md` agrees: gh and tea are ❌ on the `commits`, `stats`, `status`, and `commit` rows. ## The naming rules that apply `docs/contributing/naming-conventions.md:62-84` gives the singular name to the local git wrapper and the tea-canonical plural to the forge resource. That rule produced `commit` vs `commits`. The same section records one exception: the forge branch resource is `branches-remote`, not `branches`, because `branch` vs `branches` "reads as tea jargon and confuses non-tea users". `commit` vs `commits` has the same problem. `status` mirrors `git status`, and a local wrapper matches git exactly, so `status` keeps its name. `stats` has no gh or tea equivalent, so rule 3 of the convention applies: pick a clear name. ## Candidate names I have not picked the names yet. - `commits` / `madt_commits`: `commits-remote` / `madt_commits_remote`. This follows the `branches-remote` precedent, so it is a second recorded exception to ADR 0016. - `stats` / `madt_stats`: `insights` / `madt_insights` (the name GitHub's web UI gives to the same data), or `analytics` / `madt_analytics`. ## Acceptance criteria - [ ] The CLI command and the MCP tool use the new name on both surfaces. No alias stays behind (naming-conventions.md bans aliases). - [ ] `stats usage` moves with the rest of `stats`. - [ ] ADR 0016 records the `commits` exception next to the `branches-remote` one, and the naming-conventions.md table gains its row. - [ ] The parity test in `internal/parity/` passes on the new names. - [ ] `endpointSuggestions` in `internal/service/api/suggestions.go`, `docs/COMPARISON.md`, the help topics, the server instructions, and the generated reference docs use the new names. - [ ] Every tool description that names `madt_commits` or `madt_stats` uses the new name.

hexajon commented

2026-10-02 20:17:59 +00:00

Author

Owner

Source for the insights candidate: GitHub's docs put the contributors graph under the repository's Insights tab (https://docs.github.com/en/repositories/viewing-activity-and-data-for-your-repository/viewing-a-projects-contributors). The same tab holds Pulse, Commits, Code frequency, and Traffic (https://docs.github.com/en/repositories/viewing-activity-and-data-for-your-repository/about-repository-graphs).

Correction to the body: Insights matches the contributor and commit data in madt_stats, not all of it. The org totals and the issue time-to-close in madt_stats have no Insights equivalent.

Source for the `insights` candidate: GitHub's docs put the contributors graph under the repository's Insights tab (https://docs.github.com/en/repositories/viewing-activity-and-data-for-your-repository/viewing-a-projects-contributors). The same tab holds Pulse, Commits, Code frequency, and Traffic (https://docs.github.com/en/repositories/viewing-activity-and-data-for-your-repository/about-repository-graphs). Correction to the body: Insights matches the contributor and commit data in `madt_stats`, not all of it. The org totals and the issue time-to-close in `madt_stats` have no Insights equivalent.

hexajon referenced this issue

2026-10-03 20:29:04 +00:00

bug(hooks,mcp): hand-written madt_ call strings drift from the registered tool surface #706

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#690

No description provided.

Rows
Columns