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.MariusStorhaug commentedon Nov 11, 2026
Campaign merge hold (2026-11-11): the user explicitly selected "Hold the six merges until validation is available (Recommended)". The current default branch has no authored validation workflow and this PR has no actual validation checks; manual prose/interface inspection is not counted as CI. Hold #92 until actual validation is available or a new explicit owner decision changes this hold. This is not authorization to add tooling, change rules, waive checks, or revive withdrawn validation work. Prepared source and existing PR/Agent-merge settings stay unchanged.
MariusStorhaug commentedon Nov 11, 2026
Fresh exact-head validation for merge preparation
On 2026-11-11, the existing isolated worktree was clean at accepted head
a6c020d4e2227397e4766f3f6daefb8d360116a6; local bytes match that source. The full diff against4e0092de8f208b11e0d4607ced93471607aa748estill contains only the three assigned issue forms, andgit diff --checkpasses. No source was changed.One-time static inspection of the three parsed forms preserves every non-prose key/value/order/type, comments, routing/metadata, required fields and render identifiers; it examines all ten approved display values and four exact inline command examples. Feature and blank-issue configuration bytes are unchanged in this PR. No retained test or simulated GitHub runtime is added.
The existing cached
markdownlint-cli2 0.23.2/markdownlint 0.41.1ran on ten extracted display strings with the immutable shared MSX Markdown config blobd48dd486e4d3a968fceee23a62a84a71694b88c2, held outside the repository: ten files examined, zero issues, exit 0. GitHub's native Markdown API also rendered all ten actual display strings and preserved the four inline code examples. This is native Markdown rendering, not evidence of live form rendering, submission, label application, or routing. Both unchanged GitHub schema-reference URLs are available.The installed
yamllint 1.38.0was run with its explicit built-in default (--strict -d default), not an invented shared override or claimed hosted configuration. Baseline: sixteen line-length errors and three document-start warnings. Current head: six unchanged comment-URL line-length errors and three unchanged document-start warnings, strict exit 1. These diagnostics are disclosed, not counted as a pass or hidden by suppression; no related source or tooling is changed.Fresh live review readback is
APPROVEDon this exact head, with zero review threads. Existing exact-head approval5768188582is retained; no new review execution is claimed. GitHub currently returns zero check runs and zero status contexts, with combined statuspendingover an empty list. Missing hosted CI is not a pass. Effective native rules contain no required-status-check rule; the existing repository validation ruleset has no rules. No failing required check is bypassed.The user's live merge direction supersedes the earlier draft-only lifecycle instruction. This PR is open and non-draft; operational acceptance and the root's exclusive merge slot are still required. No merge,
merge_prchange, auto-merge, rule/setting change, new tooling, or live test issue is performed by this validation.MariusStorhaug commentedon Nov 11, 2026
Supplemental pinned shipped-default YAML comparison
The fresh comparison also ran the exact unmodified configuration shipped by Super-Linter commit
4ce20838b8ab83717e78138c5b3a1407148e0918, Git blob2aa49bd1867e24acdea4172191922df6135b69c6. Its tool manifest specifiesyamllint==1.38.0, matching the already installed tool. The downloaded config remains outside the repository and no rule is changed.This is the pinned linter's shipped default, not a PSModule/.github-owned/shared YAML override or proof that this repository runs hosted CI. For the three forms, baseline has sixteen line-length warnings plus three document-start warnings. Candidate
a6c020d4e2227397e4766f3f6daefb8d360116a6has six unchanged comment-URL line-length warnings plus three unchanged document-start warnings, with no error-severity findings. Every file exits0in normal mode and2in strict warning-as-failure mode. Normal exit0is not a warning-free claim.The earlier explicit installed built-in-default result remains distinct: candidate has six line-length errors and three document-start warnings, strict exit
1. Neither result is hidden, reclassified as hosted enforcement, or used to weaken rules. No accepted source, machine contract, command example, dependency, validation workflow, hook, ruleset, or label changed. The root coordinator decides operational acceptance from the fresh evidence; no merge ormerge_prchange is performed here.Community guidance gives direct, condition-first instructions (#95)
MariusStorhaug commentedon Nov 11, 2026
Actual merge and completion receipt
PSModule/.github#92 merged by ordinary exact-head squash at
11/11/2026 17:34:55. Accepted source:a6c020d4e2227397e4766f3f6daefb8d360116a6. Integrated commit:55a1fc5834db0d9437d8fcef995cf6e3f25a996f, with parent236da40b86a43c498ef7e6d3208de8e969364984.Fresh tree/delta inspection verifies the accepted owned-file blobs exactly in the integrated commit and only these changed paths:
.github/ISSUE_TEMPLATE/01-bug.yml,.github/ISSUE_TEMPLATE/02-patch.yml,.github/ISSUE_TEMPLATE/99-general.yml. The current final campaign main is33cd02fee689009de3ddcc3aed26d6e11d7fe04b; cumulative verification preserves all ten accepted documentation blobs and all unrelated source. The remote topic branch is deleted (ref GET returns 404). This PR's only completion leaf is this existing Task, now closed as completed.The merge used the normal protected route with an exact-head guard, no admin/force/bypass, no source or infrastructure change, no broad auto-merge, and no
merge_prchange. Current post-merge check-run/status/workflow-run sets are empty; no actual job remains in flight. Absence of hosted CI is not a pass, and the fresh static/native-markup/interface/link evidence and accepted unchanged baseline YAML findings retain their exact limits. These are Git-served default files; no Pages, package publication, downstream rollout, live form submission, or mailbox experiment is required or claimed.