hand-github: /update-pr-description changes based on research of good PR descriptions#128
Draft
mxriverlynn wants to merge 5 commits into
Draft
hand-github: /update-pr-description changes based on research of good PR descriptions#128mxriverlynn wants to merge 5 commits into
mxriverlynn wants to merge 5 commits into
Conversation
Specify the rebuild of update-pr-description from the effective-pull-request-descriptions research: a claim-by-claim verification gate against diff evidence, a non-blocking oversized-change warning, and an authoring pass built for writing rather than critique.
All three reviewers independently found the first draft's gate could be waved through in one action, reproducing the failure mode it exists to prevent. The gate now blocks on unevidenced claims, absence claims, and intent; drops the automation- biasing 'supported' label; fails closed on an unanswered question; and discloses what publishing destroys. Readability folds into the authoring pass so no generative pass runs between claim provenance and the gate.
Fix the D-to-F finding mappings (shifted by one from D13 on), promote trivial decisions to linkable headings, and close four contradictions synthesis surfaced: the not-applicable note was banned after rejection but mandated during drafting; two further rewrite passes survived the readability fix and would have gutted the gate; re-rendered text was never shown to the engineer; and the intent item's blocking rule collided with stating intent up front. Add D22 for the branch-state guards, and carry the preprint caveat on A13/A27 instead of laundering it.
Four specialists reviewed the spec. Three independently found the same structural hole: the gate blocked only on claims the skill reported as unevidenced, but a fabricated claim usually arrives with a confident pointer at a real hunk, so it landed in the tier a single keystroke cleared. The bulk-accept path had become the 'supported' badge D2 deleted. An adversarial pass now refutes each claim against its evidence before the gate and demotes what it refutes. It reads only and never touches the words, which keeps D11 and T1 intact (T2). The investigator also refuted three 'carried forward' claims against the skill on disk: the gh CLI hard stop D22 never mentions, the replace-scaffold template state the spec's two-state model denies, and the reading-order guide's exemption, whose premise the skill's own content rule contradicts. Adds D23-D31, T2, and the review companion files. 29 findings, F25-F53.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
[WIP - DO NOT MERGE]
looking into updates for the pr description skill based on research.