Repository navigation
[documentation-writing-alignment] State community issue-form instructions directly #91
Description
Describe the change
Context and request
People who submit bug, patch, and general issues need direct instructions about the information to provide. The writing-alignment review uses PSModule/.github source 4e0092de8f208b11e0d4607ced93471607aa748e and the fixed MSX documentation baseline. This Task owns one focused prose-only draft PR for .github/ISSUE_TEMPLATE/01-bug.yml, 02-patch.yml, and 99-general.yml.
Confirmed evidence
| Target text | Source-backed gap |
|---|---|
| All three forms open with "Thanks for taking the time" and ask for "as much information as possible so we can help you quickly." | Courtesy filler, an unbounded request, and an unsupported response-speed promise replace a concrete instruction. Natural Language: Be direct and specific and Write evergreen prose require specific current guidance without vague promises. |
| The bug form uses "vs.", "what you're trying to do", "when encountering the bug", and lower-case "powershell" in its instructions. | Use unambiguous active sentences and the exact technical name PowerShell, while preserving the requested evidence and command syntax. Writing Guide preserves technical meaning and artifact contracts. |
| Patch asks for "what you would want to change"; general asks only for "A clear and concise description." | State the existing request directly without introducing extra mandatory evidence or a technical plan. The official STEMG FAQ supports active, imperative procedural instructions rather than indirect prose. |
Acceptance criteria
- The three form introductions state what the person must describe, without thanks, conversational filler, unbounded requests, or response-time promises.
- Bug prompts continue to request the problem and expected behavior, version details, reproduction steps, code, and relevant output. The exact examples
$PSVersionTable,Get-Module -ListAvailable -Name 'ModuleName',-Debug, and-Verboseremain unchanged. - Patch and general prompts express their existing requested information directly. No new required evidence, fields, technical plan, policy, or intake workflow is added.
- Preserve form names, chooser descriptions, title prefixes, declared labels, field IDs, machine keys, field types/order, required flags, render values, and all routing behavior. Reader-facing introduction and field description strings are the change boundary; existing textarea labels remain unchanged.
.github/ISSUE_TEMPLATE/10-feature.ymlremains untouched under its existing owner in PSModule/.github#89.config.ymlretainsblank_issues_enabled: true.- New and changed prose uses en-US, short active sentences, stable technical terms, and source-supported ASD-STE100 Issue 9 practices. Instructions remain direct imperatives; historical inputs such as a reported bug version are not misrepresented as present-state facts.
- The focused PR carries concrete before/after evidence and read-only interface inspection, reports static checks and pre-existing diagnostics honestly, and remains draft, open, and unmerged with no auto-merge or Agent merge.
Constraints and prior ownership
The existing feature-form owner confirmed no ownership conflict for these three paths. The user chose "Revise the prose and preserve the form behavior (Recommended)" for PSModule/.github#89. That owner revises only .github/ISSUE_TEMPLATE/10-feature.yml prose and preserves form behavior, lifecycle settings, Agent-merge settings, and testing-policy cleanup. This Task leaves that file untouched and does not duplicate its work. The owner of withdrawn PSModule/.github#86 confirmed no active ownership of these paths. PSModule/.github#87 is separate, unimplemented YAML validation work, not a prerequisite or a closing issue for this prose-only Task. Do not revive withdrawn validation/governance work, add scripts, tests, linters, dependencies, hooks, workflow files, or a simulated GitHub runtime. Do not submit a test issue or claim live GitHub form validation.
Technical decisions
Edit only introduction and field-description prose in the three owned forms, with line wrapping only where needed for edited prose. Preserve comments and exact URLs, all machine fields, and native schema behavior. Do not change the feature form, blank-issue configuration, public/private support routes, PR templates, or any other documentation.
Apply the fixed baseline Natural Language, Writing Guide, Documentation Model, and applicable artifact formats. A GitHub issue form keeps its schema and prompt format; it is not rewritten as a spec, design, or declarative narrative. Consult the official STEMG explanation, FAQ, and Issue 9 when a rule or dictionary detail matters. Keep full references local and do not claim complete STE conformance from lint or word counts.
Use the existing installed yamllint --strict and Git diff/whitespace inspection. Capture baseline diagnostics first: the inherited forms have long immutable comment URLs and document-start warnings. These unrelated pre-existing YAML diagnostics are not permission to add tooling, weaken rules, or enlarge this Task. Parsed schema/diff inspection is one-time static maintenance evidence, not a retained snapshot test or evidence of live GitHub behavior.
Implementation plan
- Read all three owned forms and the repository guidance. Capture baseline prose, source identity, existing static diagnostics, and unchanged machine-interface expectations before editing.
- Make a small first commit for direct bug-form prose. Push and open the focused draft PR early with this Task as its only closing delivery leaf.
- Make a separate small commit for direct patch/general prose, preserving every field and existing evidence request.
- Inspect the exact full diff and parsed/static form structure for preserved interfaces and command examples. Run existing YAML and whitespace checks; distinguish pre-existing diagnostics and unexecuted live submission coverage.
- Complete the writing/format review and update this Task and PR with concrete acceptance evidence, source references, and completed plan progress. Leave the PR in draft for user review.
Activity
MariusStorhaug commentedon Nov 4, 2026
Implementation audit: baseline
Plan step 1 is complete. The clean worktree starts at
4e0092de8f208b11e0d4607ced93471607aa748e. The write scope is limited to.github/ISSUE_TEMPLATE/01-bug.yml,02-patch.yml, and99-general.yml.The before-change inspection confirms these gaps:
PowerShellname.Before editing,
yamllint --strict .github\ISSUE_TEMPLATE\01-bug.yml .github\ISSUE_TEMPLATE\02-patch.yml .github\ISSUE_TEMPLATE\99-general.ymlexits1with 16 line-length errors and 3 document-start warnings:01-bug.yml02-patch.yml99-general.ymlThe two comment URLs in each file and the missing document-start markers are outside the prose scope. They remain unchanged; no suppression or configuration change is planned.
The repository README, AGENTS, contribution guidance, all six required MSX pages at
MSXOrg/docs@1b0d4893c8fefabe604d04393068a8ff6f848082, and the applicable YAML/PR/commit guidance are available. The official STE explanation, FAQ, and Issue 9 DOI record are available. The local Issue 9 PDF has MD59c720341c350ed77943b2c73d01c716f, which matches the Zenodo record. The local text supports checks of active voice, imperative instructions, short sentences, and vocabulary. The manual and extracted text remain local. These checks do not certify full STE conformance.The agreed final inspection will compare the baseline and final head once as parsed YAML and a full diff. It will cover all unchanged machine keys, field order/types/IDs/labels, required flags, render values, comments, exact URLs, and command examples. The feature form and
blank_issues_enabled: trueremain outside the write scope. This is static maintenance evidence, not live form validation. No test issue, test file, new tool, or workflow is part of this Task.MariusStorhaug commentedon Nov 4, 2026
Implementation audit: bug prompts and early draft
Plan step 2 is complete. Commit
6971f42fd6c5bada3fb7b7465255f1e9be1bf080changes only bug-form introduction and description prose. The branch is pushed, and the focused draft is open at #92. This draft exists before patch/general edits.The bug introduction now says, "Give information about the bug in the fields below." The description now says, "Give a description of the bug and the behavior you expected." The version prompt retains the version used when the bug occurred. The code prompt names the intended task. The output prompt uses
PowerShell, separates the command action from the paste action, and retains the output-or-workflow-link alternative.git diff --checkpasses. Strict YAML lint on the bug form exits1with only the unchanged comment-URL errors at 1:81 and 6:81, plus the document-start warning at 2:1. The seven bug-prose line-length errors no longer occur. The exact command examples and flags remain unchanged in the reviewed diff.The native issue type is
Task, with no blocked-by issues. Next: patch/general prose in the second small commit, followed by final parsed/diff inspection and complete acceptance evidence. The draft stays open and unmerged, with no auto-merge or Agent merge.MariusStorhaug commentedon Nov 4, 2026
Implementation audit: patch and general prompts
Plan step 3 is complete. Commit
a6c020d4e2227397e4766f3f6daefb8d360116a6(Give direct instructions for patch and general issues) is pushed to the existing draft.The second commit changes only these four existing prose values. It adds no evidence request, field, or technical plan. The reviewed diff has no whitespace errors. Strict lint on patch/general exits
1with only the four unchanged long comment URLs and two document-start warnings. Final full-scope parsed/static inspection is in progress at the exact head above.MariusStorhaug commentedon Nov 4, 2026
Implementation audit: final acceptance evidence
All five implementation-plan steps are complete for this prose-only delivery. The draft is #92. Its exact head is
a6c020d4e2227397e4766f3f6daefb8d360116a6, compared with source4e0092de8f208b11e0d4607ced93471607aa748e.6971f42fd6c5bada3fb7b7465255f1e9be1bf080a6c020d4e2227397e4766f3f6daefb8d360116a6Only
.github\ISSUE_TEMPLATE\01-bug.yml,.github\ISSUE_TEMPLATE\02-patch.yml, and.github\ISSUE_TEMPLATE\99-general.ymlchange: 17 additions, 13 deletions, and ten existing prose values (6/2/2). No other file or delivery session is created.Acceptance results
PowerShellhas the correct capitalization in prose. The run and paste actions are separate sentences.0. It compares the baseline and exact final-head Git content and permits only the introduction value and existing textarea description values to differ. Names, chooser descriptions, title prefixes, labels, all keys and key order, scalar types, body types/order, IDs, textarea labels, required flags, and render values match. All seven textareas remain required.$PSVersionTable,Get-Module -ListAvailable -Name 'ModuleName',-Debug, and-Verbosematch in both source revisions. The render identifierspowershellandShellremain unchanged.10-feature.ymlandconfig.ymlhave identical Git content at the baseline and final head.blank_issues_enabled: trueremains unchanged. The feature form and all other owners' paths are untouched.git diff --checkexits0, and the worktree is clean.Strict YAML results
The same strict command on the three owned forms exits
1before and after the change. Before: 16 line-length errors and 3 document-start warnings. Final: 6 line-length errors and 3 document-start warnings. The ten prose line-length errors no longer occur.Each form retains exactly these baseline diagnostics:
1:81(139 > 80 characters),6:81(142 > 80 characters), and2:1(missing document start). The two errors concern unchanged comment URLs. These lines and the document starts are outside scope. No diagnostic is hidden, no rule is weakened, and no new tooling is added. The separate YAML-validation Task #87 remains unimplemented by this PR and is not a prerequisite or closing issue.Writing, sources, and review
The required six MSX pages were available and read at
MSXOrg/docs@1b0d4893c8fefabe604d04393068a8ff6f848082. The official STE explanation, FAQ, DOI record, and local Issue 9 references were available. The local PDF MD59c720341c350ed77943b2c73d01c716fmatches Zenodo. The review consulted the local rules/dictionary for active voice, short imperative instructions, and vocabulary. The manual and extracted text remain local. The final prose uses en-US and keeps native issue-form instructions imperative; historical bug evidence remains historical. This review does not certify full STE conformance.The fixed PR format contains one contributor-facing
Changedresult, section-scoped evidence and references, andResolves PSModule/.github#91as the only closing delivery leaf. The standards/domain review and scoped issue-convergence search are recorded there. The search also returned #87, #88, and #90; their separate outcomes are not delivered by this diff.The explicitly requested exact-head review approved the final head at
2026-11-04T12:24:49Z, with no active review issues and zero inline comments.These are static maintenance checks. No functional/live form rendering, submission, label application, or routing test is executed. No test issue, test file, retained snapshot assertion, simulated runtime, validator, dependency, hook, or workflow is introduced.
There is no delivery blocker within this prose scope. The strict YAML limitations remain explicit. The PR stays draft, open, and unmerged; auto-merge is not enabled and Agent merge is disabled. User-directed draft retention overrides the normal ready/automatic-landing step. This Task stays open for the draft's merge lifecycle.
MariusStorhaug commentedon Nov 4, 2026
Metadata audit
The Task body now marks all five Implementation plan items complete. It replaces the superseded feature-copy hold with the user's authorization for the existing owner to revise feature prose in #89 while preserving form behavior, lifecycle/Agent-merge settings, and testing-policy cleanup. The scopes remain disjoint; this Task leaves
10-feature.ymluntouched and does not duplicate that work.Readback confirms five checked items, zero unchecked items, no stale hold sentence, and no other body-text change. The issue remains open. No repository file, PR body, source commit, or lifecycle setting changed. PR #92 remains draft, open, and unmerged at
a6c020d4e2227397e4766f3f6daefb8d360116a6; the worktree is clean.