Epic: adr tooling guides the author, not only fails #496

New issue

Open

opened 2026-09-15 21:07:32 +00:00 by hexajon · 0 comments

hexajon commented

2026-09-15 21:07:32 +00:00

Owner

Goal

An author, human or agent, can create, decide, and supersede an ADR with madtea and pass adr check on the first try. The tool says what to do next. When something is wrong, it says what and how to fix it, in plain words.

Design

Mechanics stay in Go: init, new, check, and any status-change actions. They must be exact, testable, and work for the CLI, every MCP client, and CI.
Guidance lives in the server (tool output and madt_help), so every client gets it. A skill may add a Claude Code trigger on top.
No rule codes in anything a person reads.

Children

#492 plain-English adr check messages
#493 lifecycle guidance: next steps after new, a lifecycle help section
#494 decision: default for the linked-issue rule
#495 actions to decide and supersede a record

Related: #491 (CI runs only the file checks), #488 (ship MADR support in a release).

Exit criterion

All children closed. A new record created with adr new and taken to accepted with madtea's own actions passes adr check with no hand fixes.

#509

## Goal An author, human or agent, can create, decide, and supersede an ADR with madtea and pass `adr check` on the first try. The tool says what to do next. When something is wrong, it says what and how to fix it, in plain words. ## Design - Mechanics stay in Go: `init`, `new`, `check`, and any status-change actions. They must be exact, testable, and work for the CLI, every MCP client, and CI. - Guidance lives in the server (tool output and `madt_help`), so every client gets it. A skill may add a Claude Code trigger on top. - No rule codes in anything a person reads. ## Children - #492 plain-English `adr check` messages - #493 lifecycle guidance: next steps after `new`, a lifecycle help section - #494 decision: default for the linked-issue rule - #495 actions to decide and supersede a record Related: #491 (CI runs only the file checks), #488 (ship MADR support in a release). ## Exit criterion All children closed. A new record created with `adr new` and taken to accepted with madtea's own actions passes `adr check` with no hand fixes.  - [ ] #509

hexajon added the

epic

label

2026-09-15 21:07:32 +00:00

hexajon added a new dependency

2026-09-15 21:08:18 +00:00

#492 adr check: say what is wrong and how to fix it, in plain words, with no rule codes

hexajon added a new dependency

2026-09-15 21:08:18 +00:00

#493 adr: guide the author through the record lifecycle (next steps after new, a lifecycle help section)

hexajon added a new dependency

2026-09-15 21:08:18 +00:00