decision: should shipped scripts and hooks state the reason inline instead of citing an issue number? #738

New issue

Open

opened 2026-10-07 18:43:36 +00:00 by hexajon · 0 comments

hexajon commented

2026-10-07 18:43:36 +00:00

Owner

The question

#15 set the principle for user-facing steering and refusal text: shipped strings carry the rule, not the reference. Script and hook header comments are a gray area - they ship (the hooks reach plugin users, the operator scripts ship in the repo), and several cite a bare issue number as the justification for a check or a step.

Should that principle extend to those headers - state the reason inline, never point at an issue number - or is an issue citation acceptable there as contributor context?

Not decided

Open question. If the answer is yes, it sets the standard the cleanup follow-up applies, and stops the citations creeping back.

Example of the swap

# Why this exists (issue #47): the running Go must exactly match go.mod
becomes
# Why this exists: the running Go must exactly match go.mod, so a stale toolchain cannot ship.

## The question #15 set the principle for user-facing steering and refusal text: shipped strings carry the rule, not the reference. Script and hook header comments are a gray area - they ship (the hooks reach plugin users, the operator scripts ship in the repo), and several cite a bare issue number as the justification for a check or a step. Should that principle extend to those headers - state the reason inline, never point at an issue number - or is an issue citation acceptable there as contributor context? ## Not decided Open question. If the answer is yes, it sets the standard the cleanup follow-up applies, and stops the citations creeping back. ## Example of the swap `# Why this exists (issue #47): the running Go must exactly match go.mod` becomes `# Why this exists: the running Go must exactly match go.mod, so a stale toolchain cannot ship.`

hexajon added the

enhancement

status/needs-decision

labels

2026-10-07 18:43:36 +00:00

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

No description provided.

Rows
Columns