@bompus/house-rules 0.0.0-stage → 0.13.0

package/skills/hr-code-review/scripts/panel-preferences.mjs

@@ -0,0 +1,220 @@
+// Portable panel preferences and a pure resolver. See ../references/panel-plan.md.
+// Exact model/provider bindings come from a user-owned file; nothing here calls a model.
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const alias = /^[a-z][a-z0-9-]{0,63}$/;
+
+function keys(value, required, optional, path) {
+  if (!object(value)) throw new Error(`${path} must be an object`);
+  for (const key of required)
+    if (!Object.hasOwn(value, key)) throw new Error(`${path}.${key} is required`);
+  for (const key of Object.keys(value))
+    if (![...required, ...optional].includes(key)) throw new Error(`unknown ${path}.${key}`);
+}
+
+export function validatePanelPreferences(value) {
+  keys(value, ["version", "roles", "policy"], ["profile"], "panel");
+  if (value.version !== 1) throw new Error("panel.version must be 1");
+  if (value.profile !== undefined && !["quick", "balanced", "deep"].includes(value.profile))
+    throw new Error("panel.profile must be quick, balanced or deep");
+  if (!Array.isArray(value.roles) || value.roles.length === 0)
+    throw new Error("panel.roles must be a non-empty array");
+  const ids = new Set();
+  for (const [index, role] of value.roles.entries()) {
+    const path = `panel.roles[${index}]`;
+    keys(role, ["id", "candidates"], [], path);
+    if (typeof role.id !== "string" || !alias.test(role.id))
+      throw new Error(`${path}.id must be a lowercase alias (letters, digits and hyphens)`);
+    if (ids.has(role.id)) throw new Error(`duplicate panel role "${role.id}"`);
+    ids.add(role.id);
+    if (
+      !Array.isArray(role.candidates) ||
+      role.candidates.length === 0 ||
+      role.candidates.some((candidate) => typeof candidate !== "string" || !alias.test(candidate))
+    )
+      throw new Error(`${path}.candidates must be a non-empty array of lowercase aliases`);
+    if (new Set(role.candidates).size !== role.candidates.length)
+      throw new Error(`${path}.candidates contains duplicates`);
+  }
+  keys(
+    value.policy,
+    ["fallback", "roundLimit", "meteredRoutes"],
+    ["distinctFamilies", "excludeAuthorFamily", "allowReducedPanel"],
+    "panel.policy",
+  );
+  for (const key of ["distinctFamilies", "excludeAuthorFamily", "allowReducedPanel"])
+    if (value.policy[key] !== undefined && typeof value.policy[key] !== "boolean")
+      throw new Error(`panel.policy.${key} must be boolean`);
+  if (!["none", "approved-only"].includes(value.policy.fallback))
+    throw new Error("panel.policy.fallback must be none or approved-only");
+  if (!Number.isSafeInteger(value.policy.roundLimit) || value.policy.roundLimit < 1)
+    throw new Error("panel.policy.roundLimit must be a positive safe integer");
+  if (!["included-only", "explicit-approval-required"].includes(value.policy.meteredRoutes))
+    throw new Error(
+      "panel.policy.meteredRoutes must be included-only or explicit-approval-required",
+    );
+}
+
+export function changePanelPreferences(config, value) {
+  validatePanelPreferences(value);
+  return { ...structuredClone(config), panel: structuredClone(value) };
+}
+
+const familyName = /^[a-z][a-z0-9-]{0,63}$/;
+
+export function validatePanelBindings(value) {
+  keys(value, ["version", "aliases"], [], "bindings");
+  if (value.version !== 1) throw new Error("bindings.version must be 1");
+  if (!object(value.aliases)) throw new Error("bindings.aliases must be an object");
+  for (const [name, binding] of Object.entries(value.aliases)) {
+    const path = `bindings.aliases.${name}`;
+    if (!alias.test(name))
+      throw new Error(`${path}: alias must be lowercase letters, digits and hyphens`);
+    keys(binding, ["launch"], ["families", "metered"], path);
+    if (!object(binding.launch) || Object.keys(binding.launch).length === 0)
+      throw new Error(`${path}.launch must be a non-empty object`);
+    if (
+      binding.families !== undefined &&
+      (!Array.isArray(binding.families) ||
+        binding.families.length === 0 ||
+        binding.families.some((family) => typeof family !== "string" || !familyName.test(family)) ||
+        new Set(binding.families).size !== binding.families.length)
+    )
+      throw new Error(`${path}.families must be a non-empty array of distinct lowercase names`);
+    if (binding.metered !== undefined && typeof binding.metered !== "boolean")
+      throw new Error(`${path}.metered must be boolean`);
+  }
+}
+
+// Project and task layers may only tighten the user's policy.
+function combinePolicy(layers) {
+  const policies = layers.map((layer) => layer.policy);
+  const [user] = policies;
+  return {
+    fallback: policies.some((p) => p.fallback === "none") ? "none" : "approved-only",
+    roundLimit: Math.min(...policies.map((p) => p.roundLimit)),
+    meteredRoutes: policies.some((p) => p.meteredRoutes === "included-only")
+      ? "included-only"
+      : "explicit-approval-required",
+    distinctFamilies: policies.some((p) => p.distinctFamilies === true),
+    excludeAuthorFamily: policies.some((p) => p.excludeAuthorFamily === true),
+    allowReducedPanel:
+      user.allowReducedPanel === true && policies.every((p) => p.allowReducedPanel !== false),
+  };
+}
+
+// A later layer replaces a role's whole ordered candidate list; new role ids append.
+function combineRoles(layers) {
+  const roles = new Map();
+  for (const layer of layers)
+    for (const role of layer.roles) roles.set(role.id, [...role.candidates]);
+  return [...roles].map(([id, candidates]) => ({ id, candidates }));
+}
+
+function assign(roles, index, taken, chosen, distinct) {
+  if (index === roles.length) return chosen;
+  for (const option of roles[index].options) {
+    if (distinct && option.families.some((family) => taken.has(family))) continue;
+    const next = assign(
+      roles,
+      index + 1,
+      new Set([...taken, ...option.families]),
+      [...chosen, { role: roles[index].id, ...option }],
+      distinct,
+    );
+    if (next) return next;
+  }
+  return null;
+}
+
+/**
+ * request: { user, project?, task?, bindings, authorFamilies?, approvals?: { project?, metered? } }
+ * Returns { ok, seats, reduced, rejected, blockers, roundLimit, policy }; never launches a seat.
+ */
+export function resolvePanel(request) {
+  const { user, project, task, bindings, authorFamilies = [], approvals = {} } = request;
+  validatePanelPreferences(user);
+  validatePanelBindings(bindings);
+  const blockers = [];
+  const layers = [user];
+  for (const [name, layer] of [
+    ["project", project],
+    ["task", task],
+  ]) {
+    if (layer === undefined) continue;
+    validatePanelPreferences(layer);
+    if (name === "project" && approvals.project !== true)
+      blockers.push({ message: "project panel preferences are not approved" });
+    else layers.push(layer);
+  }
+  const policy = combinePolicy(layers);
+  const strictFamilies = policy.distinctFamilies || policy.excludeAuthorFamily;
+  if (policy.excludeAuthorFamily && authorFamilies.length === 0)
+    blockers.push({ message: "author family is unknown, so it cannot be excluded" });
+  const metered = new Set(approvals.metered ?? []);
+  const rejected = [];
+  const reduced = [];
+  const roles = [];
+  for (const role of combineRoles(layers)) {
+    const options = [];
+    const candidates = policy.fallback === "none" ? role.candidates.slice(0, 1) : role.candidates;
+    for (const name of candidates) {
+      const binding = Object.hasOwn(bindings.aliases, name) ? bindings.aliases[name] : undefined;
+      const reject = (reason) => rejected.push({ role: role.id, alias: name, reason });
+      if (binding === undefined) reject("no binding for this alias");
+      else if (strictFamilies && binding.families === undefined) reject("model family is unknown");
+      else if (
+        policy.excludeAuthorFamily &&
+        binding.families.some((f) => authorFamilies.includes(f))
+      )
+        reject("shares a model family with the author");
+      else if (binding.metered === true && policy.meteredRoutes === "included-only")
+        reject("metered route is not allowed by an included-only policy");
+      else if (binding.metered === true && !metered.has(name))
+        reject("metered route needs explicit approval");
+      else
+        options.push({
+          alias: name,
+          families: binding.families ?? [],
+          metered: binding.metered === true,
+          launch: binding.launch,
+        });
+    }
+    if (options.length > 0) roles.push({ id: role.id, options });
+    else if (policy.allowReducedPanel) reduced.push(role.id);
+    else blockers.push({ role: role.id, message: `no eligible route for role "${role.id}"` });
+  }
+  let seats = [];
+  if (blockers.length === 0) {
+    if (roles.length === 0) blockers.push({ message: "no role has an eligible route" });
+    else {
+      seats = assign(roles, 0, new Set(), [], policy.distinctFamilies);
+      if (seats === null) {
+        seats = [];
+        blockers.push({ message: "no assignment gives every seat a distinct model family" });
+      }
+    }
+  }
+  return {
+    ok: blockers.length === 0,
+    seats,
+    reduced,
+    rejected,
+    blockers,
+    roundLimit: policy.roundLimit,
+    policy,
+  };
+}
+
+export function formatPanelPlan(plan) {
+  const lines = [plan.ok ? "Panel plan (no model has been called):" : "Panel blocked:"];
+  for (const seat of plan.seats) {
+    const families = seat.families.length > 0 ? seat.families.join("+") : "unknown";
+    lines.push(`  ${seat.role}: ${seat.alias} (${families}${seat.metered ? ", metered" : ""})`);
+  }
+  for (const role of plan.reduced) lines.push(`  ${role}: dropped, no eligible route`);
+  for (const blocker of plan.blockers) lines.push(`  blocker: ${blocker.message}`);
+  for (const item of plan.rejected)
+    lines.push(`  skipped ${item.alias} for ${item.role}: ${item.reason}`);
+  lines.push(`  rounds: ${plan.roundLimit}`);
+  return lines.join("\n");
+}

package/skills/hr-design-exploration/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: hr-design-exploration
+description: "Explore visual design or redesign alternatives through four ranked directions, top-two feedback and refinement toward one chosen design, or compare variants of one component in place. Use when asked to propose or compare UI design directions or component variants; ordinary UI fixes and implementing a chosen design do not need it."
+---
+
+# Design exploration
+
+Use the user's requested scope and constraints. The default is four initial
+directions, then rounds containing the two selected designs and one variation
+of each. A requested count applies to the initial comparison unless the user
+also specifies refinement rounds. Refinement defaults to four options. Before
+a differently sized refinement round, agree which selected designs to retain
+and how many variations to show. The user's chosen method takes precedence.
+
+## Establish the comparison
+
+Read the brief and current design. Identify the intended users, primary task,
+content, required interactions, brand constraints and target viewports. Use
+existing answers; ask only for missing information that would change the
+alternatives. State the goal used to rank recommendations.
+
+Keep the same real content, states and viewport sizes across previews. Hold
+accessibility and required behavior constant. If content is unavailable, label
+placeholder content and the assumptions it introduces.
+
+## Show the initial directions
+
+Create four meaningfully different approaches by default to the same goal. Differences
+should affect hierarchy, layout, navigation, interaction or density. Color
+swaps alone do not make distinct directions. Stay within the authorized
+prototype scope; keep the current implementation available for comparison.
+
+Show inspectable previews at comparable sizes, using the host's available
+preview or image tools. Include interaction states when they distinguish the
+directions. If rendering is unavailable, label the output as concepts and name
+what remains unverified. Never claim an unseen design was visually checked.
+
+Give each direction a stable ID and a short descriptive name. Present the directions
+in recommendation order, strongest first. Mark the strongest choices
+"(Recommended)" and explain why they fit the stated goal. Recommendations are
+judgments; do not invent usability results, performance gains or scores.
+
+Beside the previews, use a short comparison table with each direction's ID,
+main difference, benefit and tradeoff. Keep IDs stable when rankings change.
+Ask the user to select their top two and give feedback on each, including what
+to retain and what to change. Follow the host's question format. Wait for the
+answer before narrowing or generating the next round.
+
+## One component
+
+When the scope is a single component rather than a screen or flow, build three
+variants by default. When the authorized prototype scope includes the page
+where the component renders, put them behind a switcher there, so the user
+compares them where the component actually lives; otherwise compare them
+within the scope you have. Keep the switcher and variants out of production
+code paths, and remove them once a variant is chosen.
+
+Pick one design axis and give each variant a different position on it:
+structure (grouping, order, what collapses), density (spacing, hit areas),
+emphasis (where strong color and weight go), type (scale and weight contrast)
+or voice (labels and amount of copy). Let secondary choices follow from that
+position. Variants that differ on several axes at once cannot show which
+change made the difference. Name each variant for its direction, not "Option
+A". Before ranking, name the accessibility checks every variant must pass, at
+least keyboard reach, visible focus, accessible names for controls, no
+clipping at the narrowest supported width and no meaning carried by color
+alone, plus `hr-better-accessibility`'s checks when it is available. Check
+each variant against the same list and drop any direction that fails one.
+
+Rank and refine the variants as described below.
+
+## Refine the selected two
+
+Record the chosen IDs and feedback in the task's durable design notes. Keep
+eliminated directions there so later rounds do not revive rejected ideas by
+accident. If the user chooses one as final, move to final selection below.
+
+By default, show four options again:
+
+1. The first selected design, unchanged as a comparison.
+2. The second selected design, unchanged as a comparison.
+3. One variation of the first design responding to its feedback.
+4. One variation of the second design responding to its feedback.
+
+Give variations new IDs and name their parent IDs. Explain what changed and
+which feedback it addresses. Keep the inherited strengths visible and the
+variation distinct enough to assess. Rerank the round against the goal and
+latest feedback, mark recommended choices, and ask for the next top two with
+feedback on each.
+
+Repeat this round only after a new selection. Do not add new unrelated
+concepts unless the user asks to reopen exploration. If feedback leaves no
+meaningful variation to test, offer final selection or ask which unresolved
+tradeoff needs another round instead of inventing cosmetic differences.
+
+## Final selection
+
+An explicit final choice ends exploration; no minimum round count is required.
+Record the chosen ID, accepted refinements, rejected directions and remaining
+uncertainties. Summarize the final design's layout, interactions and relevant
+responsive states so implementation can follow it.
+
+Choosing two for refinement authorizes that comparison, not promotion of a
+winner. Apply the final design within existing implementation authorization;
+when implementation or landing has not been authorized, offer that next step.

package/skills/hr-design-exploration/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "HR: Design exploration"
+  short_description: "Compare design directions or component variants and refine"
+  default_prompt: "Use $hr-design-exploration to show four ranked visual directions, or three variants on one design axis for a single component, and refine my top two toward a final design."

package/skills/hr-diagnosing-bugs/NOTICE.md

@@ -0,0 +1,45 @@
+# Source notices
+
+This notice accompanies the hr-diagnosing-bugs bundle when copied on its own.
+
+## mattpocock/skills
+
+Source: https://github.com/mattpocock/skills (compared at revision `d81f3a1`)
+
+- `skills/hr-diagnosing-bugs/`: written for this repository after
+  `skills/engineering/diagnosing-bugs/`, which it shares a purpose with.
+
+Copyright (c) 2026 Matt Pocock
+
+## cursor/plugins (pstack)
+
+Source: https://github.com/cursor/plugins (compared at revision `e43c7ee`)
+
+- `skills/hr-diagnosing-bugs/SKILL.md`: § Question the premise is adapted from
+  `pstack/skills/principle-attack-the-premise/`.
+
+Copyright (c) 2026 Lauren Tan
+
+## house-rules and MIT permission notice
+
+MIT License
+
+Copyright (c) 2026 Aaron Queen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/hr-diagnosing-bugs/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: hr-diagnosing-bugs
+description: Investigate unknown-cause or intermittent bugs and performance regressions systematically. Evident fixes only on explicit diagnosis requests; exclude change reviews.
+---
+
+# Diagnosing bugs
+
+When filing an upstream bug, follow [Reporting a bug](references/reporting.md)
+for reduction, submission and fix verification.
+
+Follow project guidance for source paths, domain safeguards, tests and deployment.
+Read relevant domain documents when they help explain the affected behavior.
+Choose the next probe from the evidence; these techniques are not mandatory phases.
+
+## Choose a model when needed
+
+If the project names a benchmark-backed order for bug-finding models and
+efforts, use it. Primary, secondary and tertiary choices can change with benchmark
+results; read the current selection rather than carrying names from an old run.
+If the primary is unavailable through quota, outage or an unsupported route,
+use the next available eligible choice within authorized billing limits only
+when changing provider, model or effort is authorized. When the low-quota
+handoff rule applies, use the `hr-handoff` skill and stop, even if a model change
+was authorized. Preserve review independence and record the model, effort and fallback
+reason.
+If no eligible model is available, report the blocker.
+
+## Establish the symptom
+
+Identify expected and observed behavior and seek a repeatable signal for the
+reported failure. Source inspection and initial hypotheses can help construct it.
+Prefer an existing test, command or captured input before building a harness.
+Minimize the scenario when doing so helps distinguish causes or create a useful
+regression test; an exhaustively minimal reproduction is not a prerequisite.
+
+For intermittent failures, record attempts and failures under comparable
+conditions. Increase the reproduction rate when practical within host load and
+environment safeguards; do not impose a fixed retry count or success threshold.
+For performance regressions, establish a measured baseline before changing code.
+
+If reproduction is unavailable, continue useful source and artifact analysis,
+label hypotheses as unverified, and report what would confirm them. Ask for
+missing access or evidence only when it blocks further progress. Production
+instrumentation still requires the applicable authorization.
+
+## Distinguish causes
+
+State a falsifiable prediction for the likely cause and test it. Consider
+alternatives when evidence is ambiguous or a probe fails; there is no hypothesis
+quota. Use targeted inspection, a debugger, logs, replay, bisection or differential
+testing according to the uncertainty each resolves. Keep probes attributable by
+changing one relevant variable at a time where practical.
+
+When the cause depends on event order between actors, control the relevant
+boundaries in an implementation test. Pause a response or write, interrupt the
+process, then resume or restart it and assert the visible result. Use barriers
+or explicit signals instead of sleeps to force the failing order. When the
+failing order is unknown, the `hr-ordering-tests` skill enumerates the orderings
+through the real code and names the sequence that breaks.
+
+Keep secrets out of commands and shared artifacts; use environment variables
+for credentials and redact captured headers or logs before displaying them.
+Tag temporary instrumentation so it can be found and removed. When a human must
+perform a reproduction step, give clear steps and the expected observation.
+
+## Bound the loop
+
+When retrying a probe or fix, cap attempts per hypothesis, stop on
+no-progress (repeated identical calls, oscillation, unchanged error class),
+and enforce time/token/cost ceilings outside the agent so a stuck loop
+terminates instead of retrying.
+
+## Question the premise
+
+When two fixes that rest on the same assumption have failed the same check,
+stop fixing and test the assumption. Write it down as the one sentence every
+failed fix took for granted. Before a third fix, gather evidence that would
+show the sentence false, such as a count per input, actor or run, and keep it
+as a script that can be rerun. If the evidence contradicts the sentence, find
+what made it false and fix that, instead of compensating for it on every run.
+If the evidence supports the sentence, keep it as a record and look for the
+cause elsewhere.
+
+## Fix and verify
+
+When the confirmed cause admits more than one viable fix, such as a targeted
+workaround versus a root-cause correction, present the fixes as an offer (the house rules' § Offers) with
+rough relative effort before changing code. Mark the recommendation and name
+the right fix when it differs, with the reason: scope, risk, blast radius or
+existing debt. Skip this when the evidence supports a single obvious fix or
+the user already prescribed the remedy.
+
+Make the smallest fix supported by the evidence. Use a regression assertion that
+exercises the actual failure when a suitable seam exists and the change warrants
+it under project guidance. It must fail on the pre-fix code for the intended
+reason and pass after the fix, as `hr-test-audit` requires. Test-first ordering is optional
+unless requested or required by the project.
+
+Recheck the original symptom, including the original scenario if a minimized
+case was used. For intermittent or performance issues, compare measurements and
+report their limits. If verification is blocked or coverage lacks a suitable
+seam, state the gap rather than claiming the fix is proven or expanding the
+architecture without authorization.
+
+Remove temporary instrumentation and throwaway artifacts. Report the cause,
+change, checks actually run and remaining uncertainty. Recommend preventive work
+only when the evidence supports a concrete benefit; follow project completion
+and scope boundaries.

package/skills/hr-diagnosing-bugs/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "HR: Diagnosing Bugs"
+  short_description: "Diagnose hard bugs and regressions"

package/skills/hr-diagnosing-bugs/references/reporting.md

@@ -0,0 +1,97 @@
+# Reporting a bug
+
+Before filing, apply the submission search in your loaded agent guidance's "Repository work" section.
+If that section is unavailable, locate the local house-rules checkout and read
+`rules/core.md` there. Report an unavailable local source before submitting.
+Inspect labels, linked changes and timeline actions as well as comments.
+For the same problem and scope, add new evidence to a matching open issue.
+When a closed report still reproduces and remains materially unchanged,
+explain the failed fix or changed conditions and request reopening. If reopening
+is unavailable, file one linked follow-up. For material changes, use the
+replacement workflow below.
+
+Reduce the failure to the smallest self-contained reproduction you can verify.
+Remove unrelated code, dependencies, data and setup. Keep reducing until each
+remaining part is needed to reproduce the failure. For a library failure,
+trace the failing path and isolate its underlying runtime API or language
+operation. Use source inspection, profiling or controlled substitutions to
+choose the next reduction; a slow dependency does not establish its cause.
+
+Verify both the final reduction and the original scenario with exact commands
+and pinned versions. Preserve the inputs, output checks and relevant allocation,
+retention, concurrency or lifecycle behavior. A similar standalone failure is
+a contributor observation until evidence connects it to the original symptom.
+For performance or memory bugs, compare equivalent work under the applicable
+benchmark protocol. State units, repetitions, variability and measured controls;
+put the focused case before a larger comparison matrix.
+
+Include a cause-and-reduction note in the report: the isolated operation,
+evidence connecting it to the original failure, and remaining uncertainty.
+Test the proposed cause by changing or removing the suspected factor while
+preserving the other relevant conditions. Distinguish a reproduced operation,
+a supported causal explanation and a confirmed internal defect. Do not infer
+an engine defect merely because one runtime is slower on a library workload.
+
+Lead with one symptom, the reproduction, expected and actual text results,
+and the versions and environment needed to reproduce it. Check the current
+stable release; identify development builds separately when tested. A verified
+small reproduction can be reported while its internal cause remains unknown.
+
+Add an image or chart to the report only as the "Visuals in issues, discussions
+and comments" section of your loaded guidance describes; locate it in `rules/core.md`
+when it is not loaded.
+
+Show direct reproduction commands. Omit incidental scheduling, resource-control
+and observer wrappers from issue and pull request examples. When a control is
+required to reproduce the defect, include it and explain why. Keep exact executed
+commands in measurement records; disclose material conditions beside performance
+results without presenting local controls as prerequisites or changing historical
+conditions. This reporting choice is checked by the author, not a syntax gate.
+
+When reduction is blocked, record the attempted isolations and why the remaining
+parts are necessary before asking whether to submit the broader case.
+
+Read the repository's contribution guidance and matching issue template,
+including organization defaults. Complete required fields and checklists.
+Submit a YAML issue form (`.github/ISSUE_TEMPLATE/*.yml`) through the form
+itself. `gh issue create` cannot submit one, so the form's labels, dropdowns
+and checklist are lost, and copied headings alone do not preserve form
+metadata. When the host has a browser signed in to the user's GitHub account,
+open `https://github.com/<owner>/<repo>/issues/new?template=<file>.yml`, fill
+every field and submit it there. Use the CLI only when the repository has no
+issue form or only a Markdown template. Verify the published body and labels.
+With no signed-in browser, prepare the report and ask for access or user
+submission; do not fall back to `gh issue create` and drop the form's labels.
+
+Every issue offers the pull request, whatever the repository's triage timing.
+Waiting for a maintainer's verdict decides when you open the pull request, not
+whether the issue says one is available. State in the issue's fix or workaround
+field (or its closing lines, when the form has none) what exists and offer the
+pull request: "None applied. I can open a pull request for this once triage
+confirms the direction. <branch exists / not written yet>; <the approach or
+options I would measure>." When a branch or pull request already exists, link it
+instead.
+
+Before showing a draft to the user, run
+`node scripts/check-pr-offer.mjs <draft.md>` from this skill; it fails when that
+text does not offer a pull request or link a pull request or branch. It is a
+text match: it skips a sentence that puts a negation before "pull request" but
+cannot judge meaning, so confirm the offer is genuine yourself. Read the offer back from the
+form's fields before submitting.
+
+When an issue needs major or material changes, replace it with a new issue
+in any repository. Compare the proposed revision with the published report.
+A revision is major or material if it changes the reported problem, scope,
+reproduction mechanism or main conclusion. Carry forward relevant evidence and unresolved
+questions, and link the old and new reports both ways. Submit and verify the
+replacement before closing the old report as superseded, not fixed. Routine
+corrections and evidence that leave the report materially unchanged stay in place.
+
+Keep one active report per problem after replacement. Follow up with new
+evidence or a specific unanswered question. An absent bot comment is not
+evidence that nothing happened. Do not duplicate a report or close and reopen it merely to seek
+priority. Small examples help investigation; they do not guarantee action or a fix deadline.
+
+When a fix build is available, test the same reproduction and report the
+revision and before/after result. Distinguish triage, an open fix, a merged fix
+and a released fix. Verify the affected behavior before calling it resolved.

package/skills/hr-diagnosing-bugs/scripts/check-pr-offer.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// Fails when an issue draft neither offers a pull request nor links one.
+// usage: check-pr-offer.mjs <draft.md>   (or the draft on stdin)
+// The text checked is the "Fix applied or workaround" field when the draft has one, else the
+// draft's last lines. Run it before showing a draft to the user and again on the filed body.
+import { readFileSync } from "node:fs";
+
+const TAIL_LINES = 8;
+const FIELD = /^(?:#{1,6}\s*|\*\*)?fix applied or workaround\b/i;
+const HEADING = /^#{1,6}\s/;
+const OFFER = /pull request|github\.com\/[^\s/]+\/[^\s/]+\/(?:pull\/\d+|tree\/\S+)/i;
+// A sentence that denies the offer ("I cannot open a pull request") does not count.
+const DENIAL = /\b(?:cannot|can't|can not|won't|will not|unable|never|no|not)\b[^.]*pull request/i;
+
+// The field's text: from its heading or label to the next heading, or null when the draft has none.
+export function offerText(draft) {
+  const lines = draft.split("\n");
+  const start = lines.findIndex((l) => FIELD.test(l.trim()));
+  if (start >= 0) {
+    const end = lines.findIndex((l, i) => i > start && HEADING.test(l));
+    return lines.slice(start, end < 0 ? undefined : end).join("\n");
+  }
+  return lines
+    .filter((l) => l.trim())
+    .slice(-TAIL_LINES)
+    .join("\n");
+}
+
+export const offersPullRequest = (draft) =>
+  OFFER.test(
+    offerText(draft)
+      .split(/(?<=[.!?])\s+|\n/)
+      .filter((sentence) => !DENIAL.test(sentence))
+      .join("\n"),
+  );
+
+if (import.meta.main ?? import.meta.url === `file://${process.argv[1]}`) {
+  const draft = readFileSync(process.argv[2] ?? 0, "utf8");
+  if (offersPullRequest(draft)) {
+    process.exit(0);
+  }
+  console.error(
+    'FAIL: the "Fix applied or workaround" text (or the draft\'s closing lines) neither says "pull request" nor links one.\n' +
+      'Add the offer: "None applied. I can open a pull request for this once triage confirms the direction. <branch exists / not written yet>; <the approach I would measure>." or link the existing branch or pull request.',
+  );
+  process.exit(1);
+}