docs: explanatory issue and pull request templates (#186)

Author: bmuddha

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -6,34 +6,34 @@ body:
   - type: markdown
     attributes:
       value: >-
-        Title: describe the observable failure or regression in sentence case,
+        Title: the observable failure or regression in sentence case,
         without a category prefix or terminal punctuation.
         Example: `Duplicate submissions can strand callers until deadline`
   - type: textarea
     id: problem
     attributes:
       label: Problem
-      description: What happened? Include the relevant error or diagnostic evidence.
+      description: What happened? Relevant errors or diagnostic evidence help explain the failure.
     validations:
       required: true
   - type: textarea
     id: reproduction
     attributes:
       label: Reproduction
-      description: Give the smallest reproduction when known. Note if the failure is intermittent.
+      description: Smallest known reproduction and whether the failure is intermittent.
     validations:
       required: false
   - type: textarea
     id: expected
     attributes:
       label: Expected
-      description: Describe what should happen instead when it is not already clear from the problem.
+      description: What should happen instead, when not already clear from the problem?
     validations:
       required: false
   - type: textarea
     id: context
     attributes:
       label: Context
-      description: Add the revision, crate or path, and environment details when known and relevant.
+      description: Relevant revision, crate or path, and environment details, when known.
     validations:
       required: false

.github/ISSUE_TEMPLATE/change_request.yml

@@ -6,9 +6,9 @@ body:
   - type: markdown
     attributes:
       value: >-
-        Title: start with an imperative verb and describe the requested outcome
-        in sentence case, without a category prefix or terminal punctuation.
-        Example: `Add validator restart coverage`
+        Title: the requested outcome in sentence case, without a category prefix
+        or terminal punctuation.
+        Example: `Validator restart coverage`
   - type: textarea
     id: goal
     attributes:
@@ -27,6 +27,6 @@ body:
     id: scope
     attributes:
       label: Scope
-      description: Add boundaries or implementation scope when known and not already clear from the goal.
+      description: Known boundaries or implementation scope not already clear from the goal.
     validations:
       required: false

.github/ISSUE_TEMPLATE/question.yml

@@ -5,9 +5,9 @@ body:
   - type: markdown
     attributes:
       value: >-
-        Title: state the decision or unknown concisely in sentence case,
+        Title: the decision or unknown in sentence case,
         without a category prefix or terminal punctuation.
-        Example: `Determine whether snapshots require versioned manifests`
+        Example: `Whether snapshots require versioned manifests`
   - type: textarea
     id: question
     attributes:
@@ -19,13 +19,13 @@ body:
     id: context
     attributes:
       label: Context
-      description: Add background or prior findings when they help explain the question.
+      description: Background or prior findings that help explain the question.
     validations:
       required: false
   - type: textarea
     id: desired-output
     attributes:
       label: Desired output
-      description: Specify an answer, recommendation, prototype, or other artifact when not already clear from the question.
+      description: An answer, recommendation, prototype, or other artifact, when not already clear from the question.
     validations:
       required: false

.github/ISSUE_TEMPLATE/task.yml

@@ -6,24 +6,22 @@ body:
   - type: markdown
     attributes:
       value: >-
-        Make the intended outcome clear from the title.
+        Title: the intended outcome.
   - type: textarea
     id: scope
     attributes:
       label: Scope
       description: >-
-        Add details beyond the outcome only when useful: what needs to change,
-        why, and where it belongs. Introduce new
-        concepts before using them; do not assume familiarity with related work.
-        Link to relevant code or design context when useful.
+        Useful context beyond the outcome: what needs to change, why, and where
+        it belongs, with links to relevant code or design context.
     validations:
       required: false
   - type: textarea
     id: outcome
     attributes:
       label: Outcome
       description: >-
-        Describe the observable result that defines completion, with enough
+        The observable result that defines completion, with enough
         context to understand the task on its own.
     validations:
       required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,23 +1,22 @@
 <!--
-Title: use `<type>: <description>`, with a Conventional Commit type and a
-concise lowercase imperative description, without terminal punctuation.
-Example: `feat: add state replicator crate`
+Title: `<type>: <description>`, with a Conventional Commit type and a
+concise lowercase description, without terminal punctuation.
+Example: `refactor: simpler error handling`
 -->
 
 ## What changed
-<!-- Summarize the change at the immediate-parent diff boundary. -->
+<!-- What changed relative to the immediate parent, and why. Explanatory prose, not instructions. -->
 
-<!-- Replace ISSUE with the dedicated issue number. -->
+<!-- Dedicated issue completed by this PR, when applicable. -->
 Closes #ISSUE
 
 <!--
-Impact and Reviewer notes are optional. Include only relevant, non-obvious
-information; do not narrate the code. Omit either section when it adds no value,
-including for routine chores such as dependency updates or typo fixes.
+Impact and Reviewer notes are optional: relevant, non-obvious information only,
+without a code inventory. Routine chores may need neither section.
 -->
 
 ## Impact
-<!-- Note behavior, API, storage, compatibility, security, or performance effects. -->
+<!-- Behavior, API, storage, compatibility, security, or performance effects. -->
 
 ## Reviewer notes
-<!-- Point reviewers to invariants, sharp edges, or the highest-risk part of the diff. -->
+<!-- Invariants, sharp edges, or the highest-risk part of the diff. -->