Repository navigation
[documentation-writing-alignment] Use direct prompts in bug, patch, and general issue forms #16
Description
Describe the change
Context and request
Reporters need specific instructions that explain what information each shared issue form collects. Replace conversational filler and vague requests in the bug, patch, and general forms with direct en-US instructions. This delivery leaf covers one prose-only draft PR.
Evidence and sources
At source 0c67251812ea306543f3a14ab473ae357cfb76ac, .github/ISSUE_TEMPLATE/01-bug.yml:12-13, 02-patch.yml:12-13, and 99-general.yml:12-13 ask for “as much information as possible” and promise that “we can help you quickly.” The patch description at line 19 says “what you would want to change.” These statements add no verifiable input requirement.
The fixed Natural Language standard requires direct, specific en-US prose and removes words that do not change meaning. The Writing Guide preserves interface contracts and each artifact's format. The official STEMG FAQ explains direct imperative procedures and controlled technical terms. Consult Issue 9 for exact rules or dictionary details; an automated scan does not establish full STE conformance.
Acceptance criteria
- Each introduction names the information the form collects without thanks, politeness filler, an unlimited-information request, or a response-speed promise.
- Field prompts state concrete requested information in direct instructions. The bug form retains its expected/actual behavior, environment, reproduction, relevant-details, and supporting-evidence intent.
- Every existing YAML key, field ID, field order, field type, required flag, form name/title, label, and routing value remains unchanged. Only reader-facing prose changes.
- The diff contains only the three owned forms.
.github/ISSUE_TEMPLATE/10-feature.yml,config.yml, tests, and validation tooling remain outside this PR. - The issue and PR retain before/after evidence and exact validation commands with results. The PR remains in draft; no merge or Agent merge change occurs.
Technical decisions
Owned paths are .github/ISSUE_TEMPLATE/01-bug.yml, .github/ISSUE_TEMPLATE/02-patch.yml, and .github/ISSUE_TEMPLATE/99-general.yml. Preserve the GitHub issue-form format rather than applying a durable spec/design template. Reuse an already installed YAML parser to compare non-prose structure before and after the edit. The repository base has no validation scripts or lint configuration; unmerged #12 is not installed or enforced. Do not add a linter, dependency, test framework, policy, form field, or repository audit file for this change. #15 owns the feature form and its tests.
Implementation plan
- Read the owned forms and applicable pinned standards; capture a baseline structural comparison and concrete prose acceptance checks before editing.
- Make surgical prose changes, keep one logical change per small commit, and open the scoped draft PR early.
- Compare every non-prose YAML value and structure with the baseline; review the requested-information meaning and technical terms.
- Run the existing applicable checks,
git diff --check, and the focused structural comparison; record each command and result without claiming full STE conformance. - Review the final diff, update this plan with evidence, link only the delivery work it resolves, and leave the PR in draft.
Delivery progress
Draft MSXOrg/.github#21 opened after the first bug-form commit, e3e59ac00134eaec301506e2f01492d90faead9b. The second commit, deb2e80d65c1334a140c2f8c15eae738329542fb, completes the patch and general forms. Both commits are pushed, and the working tree is clean. The current-head Copilot review is APPROVED with no inline comments and no review threads. The PR closes only this Task and stays in draft; GitHub auto-merge is null. No merge or Agent merge action occurs.
Verification evidence
The baseline snapshot contains the complete parsed YAML for all three forms at 0c67251812ea306543f3a14ab473ae357cfb76ac. The comparison preserves mapping-key and field order, node types, scalar tags and styles, and every non-prose value. Only the three introduction strings and seven field-description strings can differ.
The focused check and snapshot remain in the implementation session's local artifacts. They are not repository scripts or CI enforcement. PowerShell commands use this local script:
$check = "$env:USERPROFILE\.copilot\session-state\73d907e5-c9b5-46c2-ab63-6404c149f36f\files\check_intake_forms.py"| Command | Baseline result | Candidate result |
|---|---|---|
python $check structure |
Passed: all three complete non-prose contracts match; no changed repository files. | The same full comparison passes as part of python $check all. Only the three owned forms differ. |
python $check prose |
Expected failure: 3 of 10 prose values pass and 7 fail. All three introductions, the bug description and environment prompt, and the patch and general descriptions fail. | All 10 prose values pass as part of python $check all. |
python $check all --forms bug |
Not run before the edit; the complete baseline checks above cover it. | Passed before the first commit: three complete contracts match and all six bug-form prose values pass. |
python $check all |
Not run as one command; the structure and prose checks above ran separately. | Passed: three complete contracts match, all 10 prose values pass, and the changed-file set contains exactly the three owned forms. |
python -m yamllint --strict .github\ISSUE_TEMPLATE\01-bug.yml .github\ISSUE_TEMPLATE\02-patch.yml .github\ISSUE_TEMPLATE\99-general.yml |
Passed, exit 0. | Passed, exit 0, with already installed yamllint 1.38.0. No dependency was added. |
git diff --check |
Not run before the edit. | Passed, exit 0. |
git diff 0c67251812ea306543f3a14ab473ae357cfb76ac --check |
Not run before the edit. | Passed, exit 0, across the complete delivery diff. |
git diff 0c67251812ea306543f3a14ab473ae357cfb76ac HEAD --check |
Not run before the edit. | Passed, exit 0, after both commits were pushed. |
git diff --cached --check |
Not run before the edit. | Passed before each small commit, exit 0. |
The source review covers the pinned Documentation Model, Natural Language, Writing Guide, Markdown, Documentation, YAML, and applicable issue and delivery-process guidance. The official STE overview and FAQ are accessible. The local Issue 9 PDF has MD5 9c720341c350ed77943b2c73d01c716f; the review uses its procedural-writing rules and relevant dictionary entries without republishing the manual or claiming full STE conformance.
The local parser is PyYAML 6.0.3. The wording checks are one-time delivery evidence, not a maintained phrase-freezing test suite. No repository test or validation file is added.
Before and after
| Surface | Baseline wording | Candidate wording |
|---|---|---|
| Bug introduction | Thanks for taking the time to fill out this bug report! Please provide as much information as possible so we can help you quickly. | This form records the expected and actual behavior, environment, steps to reproduce the problem, related information, and evidence. |
| Patch introduction | Thanks for taking the time to fill out this form! Please provide as much information as possible so we can help you quickly. | This form records the change you want to existing content or behavior. |
| General introduction | Thanks for taking the time to fill out this form! Please provide as much information as possible so we can help you quickly. | This form records the subject and related information for an issue that does not fit the other forms. |
| Bug description | A clear and concise description of what the bug is vs. what you expected to happen. | Give the expected behavior and the actual behavior. |
| Bug environment | What version, commit, platform, or configuration were you using when the problem occurred? | Give the version, commit, platform, or configuration in use when the problem occurred. |
| Patch description | A clear and concise description of what you would want to change. | Give the existing content or behavior and the change you want. |
| General description | A clear and concise description. | Give the subject of the issue and the related information. |
Manual review confirms that the bug form still asks for the same reproduction steps, commands, inputs, or conditions; related code, configuration, logs, screenshots, links, or context; and error messages or other evidence. The wording uses direct Give and Include instructions. The environment prompt retains or; it does not require every listed environment value.
No-change evidence
The parsed comparison also protects the existing top-level descriptions, all names and titles, labels, IDs, field order, types, and required flags. The bug form retains three required and two optional textareas; the patch and general forms each retain one required textarea. No input, routing rule, or submission requirement changes.
The feature form, config.yml, tests, validation tooling, README, contribution guidance, PR template, agent instructions, profile, security, and support files remain unchanged. The native form format owns these prompts; no spec/design template or capability scaffolding is needed. The repository's fallback role and central-standards link remain correct and need no edit for this prose-only slice.
The scoped convergence command gh issue list --repo MSXOrg/.github --state open --search 'in:body ISSUE_TEMPLATE' --limit 50 --json number,title,body,url returns this Task and #14. The latter owns the feature form and is not satisfied by this diff. No additional issue receives a closing reference.
Review and readiness
The final standards pass covers all three changed forms against fixed MSXOrg/docs commit 1b0d4893c8fefabe604d04393068a8ff6f848082 and the native GitHub issue-form format. The native form format, requested information, and en-US prose remain consistent. All required source material is accessible; there is no source or access blocker.
At candidate deb2e80d65c1334a140c2f8c15eae738329542fb, gh api repos/MSXOrg/.github/commits/deb2e80d65c1334a140c2f8c15eae738329542fb/check-runs --jq '{total_count,check_runs:[.check_runs[] | {name,status,conclusion,head_sha,html_url}]}' reports one completed successful copilot-pull-request-reviewer check. The commit-status API reports zero statuses. There is no repository-validation check at this head; the review check is not a substitute for one.
Hosted validation remains separate work in open #12. Its scripts and configuration are not part of this source baseline or this PR. The hosted-validation readiness gate remains open, not passed. This Task stays open until its PR is merged, and the PR stays draft as requested.
Activity
MariusStorhaug commentedon Nov 4, 2026
The baseline verification is complete. All three full non-prose YAML contracts match source 0c67251. The pre-edit prose checks report 7 failures across 10 values; the installed YAML linter passes. The body records the commands, source review, and local evidence location. The remaining work is the scoped wording change and draft PR.
MariusStorhaug commentedon Nov 4, 2026
The three-form wording change is pushed in two small commits. The draft opened after the first commit. At deb2e80, all 10 prose checks pass, every complete non-prose YAML contract matches the baseline, strict YAML lint passes, and both working-diff and baseline-to-candidate whitespace checks pass. The body records exact before/after wording, commands, unchanged areas, and the scoped issue-convergence result. The current-head review and hosted-check evidence remain pending; the PR stays draft.
MariusStorhaug commentedon Nov 4, 2026
The final delivery record is complete at deb2e80. The PR body covers all three forms, both commits, exact before/after evidence and validation results, the standards pass, and the scoped convergence check. The current-head Copilot review is APPROVED with no inline comments and zero threads. Only the reviewer check is present; hosted repository validation remains an open gate tracked separately in #12. All five plan steps are recorded as complete, but this Task stays open and the PR stays draft, with no merge automation.