From b2f490083a98ddce9553d2d6898bf7fe79d741de Mon Sep 17 00:00:00 2001
From: Nils Lehnen <30603423+iderex@users.noreply.github.com>
Date: Thu, 13 Aug 2026 09:48:26 +0200
Subject: [PATCH] Ask a new issue for the problem, the evidence and what done
 means

Two Markdown templates under .github/ISSUE_TEMPLATE/, and a config file
beside them that keeps the blank issue available.

The failure this prevents is the issue nobody can act on: a sentence
saying something is wrong, with no command behind the number in it and
no condition under which it closes. Every issue on this board states
what is wrong, what the evidence is and what done means, and until now
somebody arriving from outside had no way to learn that except by
reading issues other people had written.

Markdown rather than a YAML issue form, deliberately. A form marks
fields required and refuses to submit without them, which is a gate,
and each template here opens by saying that nothing reads it. The
config file is part of the same choice: it keeps the blank issue
available, so that a template is something a person can walk past.

Two templates rather than one, because a decision needs the options
with what each costs and what the answer forecloses, and a report of
something wrong does not. They share the request for evidence and
nothing else.

This does not close #107. That issue also owes a code of conduct, and
one with no reporting address is a document that is useless at the
moment somebody needs it. Which address this repository publishes is
entry 5 of #1.

Signed-off-by: Nils Lehnen <30603423+iderex@users.noreply.github.com>
---
 .github/ISSUE_TEMPLATE/config.yml  | 12 +++++
 .github/ISSUE_TEMPLATE/decision.md | 65 +++++++++++++++++++++++++++
 .github/ISSUE_TEMPLATE/problem.md  | 72 ++++++++++++++++++++++++++++++
 3 files changed, 149 insertions(+)
 create mode 100644 .github/ISSUE_TEMPLATE/config.yml
 create mode 100644 .github/ISSUE_TEMPLATE/decision.md
 create mode 100644 .github/ISSUE_TEMPLATE/problem.md

diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..30240d8
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,12 @@
+# Nothing here is a gate.
+#
+# The templates beside this file are prompts for a person. Keeping the blank issue
+# available is what makes the first line of each of them true: a form nobody can
+# walk past is enforcement whatever it says about itself, and somebody with
+# something to report that fits neither template should not be turned away by a
+# heading.
+#
+# No contact links. A link here publishes a route to a person, and which address
+# this repository publishes, for a vulnerability or for anything else, is entry 5
+# of #1 and is not decided.
+blank_issues_enabled: true
diff --git a/.github/ISSUE_TEMPLATE/decision.md b/.github/ISSUE_TEMPLATE/decision.md
new file mode 100644
index 0000000..7de486c
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/decision.md
@@ -0,0 +1,65 @@
+---
+name: Something here has to be decided
+about: A question this repository has to answer before code depends on the answer
+title: ''
+labels: ''
+assignees: ''
+---
+
+<!--
+Nothing reads this template. No check parses it, no heading is required, and an
+issue that deletes the whole thing and states the question in three sentences
+passes every check on this repository. It is a prompt for a person, not a gate,
+and it is written down here so that nobody mistakes a filled-in form for a
+checked one.
+
+Delete these comments and the guidance under each heading as you fill it in.
+-->
+
+## What is undecided
+
+<!--
+The question, in one sentence, and what in this repository is waiting on it.
+
+A question nothing is waiting on can be answered later and more cheaply, so say
+what stops if it stays open. Where the answer is not yours to give, say whose it
+is rather than proposing one.
+-->
+
+## The options, and what each costs
+
+<!--
+Every option genuinely on the table, each with what choosing it costs rather than
+what makes it attractive.
+
+An option listed only so that it can be dismissed in the same sentence teaches a
+later reader nothing, and the reader this heading exists for is the one proposing
+that option again in a year.
+
+Numbers carry their commands here as everywhere else:
+
+    <the command>
+    <its output>
+-->
+
+## What the answer forecloses
+
+<!--
+Each option makes one of the others expensive to reach later. Say which.
+
+This is the part that is invisible at the moment of choosing and permanent
+afterwards, and it is the reason the question is worth an issue rather than a
+sentence in a pull request.
+-->
+
+## What done means
+
+<!--
+Where the answer ends up, and what changes once it is there. Usually a record
+under `docs/decisions/`, plus every issue that named this one as what it was
+waiting for.
+
+The shape a record takes, including the reversal condition every one of them
+carries, is in `docs/decisions/0001-decision-records.md`. Do not restate it here;
+a second copy of a format is a copy that drifts.
+-->
diff --git a/.github/ISSUE_TEMPLATE/problem.md b/.github/ISSUE_TEMPLATE/problem.md
new file mode 100644
index 0000000..1328503
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/problem.md
@@ -0,0 +1,72 @@
+---
+name: Something here is wrong
+about: A defect, a gap, or a rule with nothing behind it
+title: ''
+labels: ''
+assignees: ''
+---
+
+<!--
+Nothing reads this template. No check parses it, no heading is required, and an
+issue that deletes the whole thing and says what is wrong in three sentences
+passes every check on this repository. It is a prompt for a person, not a gate,
+and it is written down here so that nobody mistakes a filled-in form for a
+checked one.
+
+Delete these comments and the guidance under each heading as you fill it in.
+-->
+
+## What is wrong
+
+<!--
+The thing that is wrong, in the words somebody reading this in a year would use.
+
+Where it is a gap rather than a defect, say what a reader expects to find and
+what they find instead. Where it is a rule with nothing behind it, say which
+sentence claims the rule and which check was supposed to refuse the violation.
+-->
+
+## The evidence
+
+<!--
+What you saw, rather than what you concluded from it.
+
+Every number here carries the command that produced it, pasted with its output,
+run against the reference a reader will have rather than against a working tree
+that has something else in it:
+
+    <the command>
+    <its output>
+
+That means every number. A count, a duration, a size, a version, a percentage,
+how many files something touches. A sentence with a number and no command is a
+claim, and the difference between a claim and evidence is one line.
+
+Where a claim cannot be backed by a command, write it as a claim and say so,
+rather than writing it as a measurement.
+-->
+
+## What done means
+
+<!--
+The condition under which this issue closes, written so that somebody other than
+you can look at the repository and say whether it has been met.
+
+"Handle this better" is not such a condition. A command that answers differently,
+a file that exists, a check that refuses something it accepts today, or a test
+that reddens when a guard is deleted, are.
+
+Where what is being asked for is a guard, say what it has to refuse. A guard
+nobody has watched fail is a guard nobody knows the direction of.
+-->
+
+## What this waits on
+
+<!--
+Anything this cannot move without: another issue, a decision nobody has taken, a
+setting on the repository that no branch can change. Naming it here is what lets
+a reader tell an issue that is ready from one that is waiting, without opening
+every issue it mentions.
+
+Delete this heading if it waits on nothing.
+-->