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

New issue

Open

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

hexajon commented

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

Owner

What happens

adr new writes a proposed record from the MADR template and fills in the status, date, decision-makers, and title. It then prints only the file, the index row, and where the number came from. Nothing tells the author what adr check requires next.

tracking= is free text, and adr new does not require an issue link. A record can be created with no linked issue and fail adr check at once.
madt_help topic="adr" lists rules, not steps. Nothing says what to do to propose, decide, or supersede a record.
The help's last section says to add madtea adr check to the gate. It does not say that the linked-issue check needs forge auth, or that --skip-remote-issues runs only the file checks, which is what CI needs (see #491).
The plugin skills do not mention ADRs.

Ask

adr new prints next steps: link the tracking issue under "More Information", fill in the sections, and how to decide the record.
adr new warns when the record links no issue.
madt_help topic="adr" gets a lifecycle section: propose, decide, supersede. Each step lists the exact file edits and issue actions.
The gate note says what CI needs: forge auth for the linked-issue check, or --skip-remote-issues.

The guidance lives in the server (help topic and tool output), so every MCP client and the CLI get it. A skill may add a trigger for Claude Code on top, but it is not the only home.

Acceptance

adr new output lists the next steps, and warns when no issue is linked.
The help topic has a lifecycle section with no rule codes.
The gate note covers CI auth and --skip-remote-issues.

## What happens `adr new` writes a proposed record from the MADR template and fills in the status, date, decision-makers, and title. It then prints only the file, the index row, and where the number came from. Nothing tells the author what `adr check` requires next. - `tracking=` is free text, and `adr new` does not require an issue link. A record can be created with no linked issue and fail `adr check` at once. - `madt_help topic="adr"` lists rules, not steps. Nothing says what to do to propose, decide, or supersede a record. - The help's last section says to add `madtea adr check` to the gate. It does not say that the linked-issue check needs forge auth, or that `--skip-remote-issues` runs only the file checks, which is what CI needs (see #491). - The plugin skills do not mention ADRs. ## Ask 1. `adr new` prints next steps: link the tracking issue under "More Information", fill in the sections, and how to decide the record. 2. `adr new` warns when the record links no issue. 3. `madt_help topic="adr"` gets a lifecycle section: propose, decide, supersede. Each step lists the exact file edits and issue actions. 4. The gate note says what CI needs: forge auth for the linked-issue check, or `--skip-remote-issues`. The guidance lives in the server (help topic and tool output), so every MCP client and the CLI get it. A skill may add a trigger for Claude Code on top, but it is not the only home. ## Acceptance - `adr new` output lists the next steps, and warns when no issue is linked. - The help topic has a lifecycle section with no rule codes. - The gate note covers CI auth and `--skip-remote-issues`.

hexajon added the

documentation

enhancement

labels

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

hexajon referenced this issue

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

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

hexajon added a new dependency

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

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