From 7032425994745a9cacd90d8ed05aab53006f78fe Mon Sep 17 00:00:00 2001 From: Jongsun Suh Date: Fri, 31 Jul 2026 07:13:16 -0400 Subject: [PATCH 1/3] Add `debug` orchestrator as the symptom-first sibling of `pr-validate` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `pr-validate` is handed a claim and looks for the observation that would falsify it. Debugging starts from a symptom and has to generate the hypothesis first, which is where the expensive failure lives: the theory is yours, nobody else is positioned to challenge it, and confirmation is cheap. Routes the symptom to the engine that owns its defect class rather than reimplementing any investigation, so both orchestrators share one set of engines. Carries `pr-validate`'s trust gates, which bind harder here — a weak instrument in review yields a claim someone challenges, in debugging it yields a theory nobody checks. --- domains/pr-workflow/skills/debug/skill.md | 101 ++++++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 domains/pr-workflow/skills/debug/skill.md diff --git a/domains/pr-workflow/skills/debug/skill.md b/domains/pr-workflow/skills/debug/skill.md new file mode 100644 index 0000000..556a1b7 --- /dev/null +++ b/domains/pr-workflow/skills/debug/skill.md @@ -0,0 +1,101 @@ +--- +name: debug +description: Locate the cause of a symptom you cannot yet explain — a crash, a leak, a flake, a production error spike, a number that moved. The sibling of pr-validate: where pr-validate is handed a claim and looks for the observation that would falsify it, this is handed a symptom and must generate the hypothesis first, then kill it. Classifies the symptom into a defect class, routes to the engine skill that owns that class (memory-leak-hunt, race-condition-proof, react-render-proof, sentry-grafana-cross-ref, extension-errors-debugging, typescript-compiler-blindspots, supply-chain-audit), and holds the investigation to the same evidence bar pr-validate applies — an instrument that cannot fail is not evidence, a null needs its sensitivity stated, and a finding is scoped to what the change introduced versus what pre-existed. Stops when the cause is located or the class is excluded, not when a plausible story is available. Triggers on /debug, or when asked to debug, diagnose, or investigate a symptom, find why something is slow, leaking, flaky, or erroring, chase a production alert to its cause, or reproduce a bug that cannot be reproduced by hand. +maturity: experimental +--- + +# /debug + +`pr-validate` is given a claim and looks for the observation that would prove it false. +This is given a **symptom** and has to produce the hypothesis before anything can falsify it. + +That difference is the whole skill. In review, the claim is someone else's and the social +pressure runs toward scepticism. In debugging, the hypothesis is *yours*, nobody else is +positioned to challenge it, and the expensive failure is building three hours of work on the +first theory that fit the first observation. + +## When To Use + +- A symptom with no established cause: a crash, a hang, a leak, an intermittent test, an + error-rate step change, a metric that moved without a deploy that explains it. +- A bug you cannot reproduce by hand and therefore cannot yet observe. +- A production signal that needs chasing back to code. + +## Do Not Use When + +- The PR states a claim and you need it settled — that is `/pr-validate`. +- The cause is known and you are validating the fix — that is `/pr-validate`, or the engine + skill directly. +- You want an after-the-fact writeup of a resolved failure — that is a postmortem, not this. + +## Workflow + +1. **State the symptom as an observation, not a theory.** "Popup memory grows ~105 MB per + open/close cycle" — not "the popup leaks because of the snow hook". The theory is the + output, never the input. +2. **Classify into a defect class** (table below). If two classes fit, run both; do not pick + the one you find more interesting. +3. **Delegate to the engine.** Each owns its own method and its own falsifier. This skill + routes and holds the bar; it does not re-implement the investigation. +4. **Kill the hypothesis before extending it.** Name the observation that would rule it out, + and go looking for that observation specifically. A hypothesis that has only ever been + confirmed has not been tested. +5. **Stop on a located cause or an excluded class.** A plausible story is not a stop condition. + +## Symptom → engine + +| Symptom | Class | Engine | +|---|---|---| +| Memory grows across a repeated flow; tab or worker dies over time | retention | `memory-leak-hunt` | +| Intermittent failure; passes on rerun; order-dependent | interleaving | `race-condition-proof` | +| UI janks, re-renders excessively, selector recomputes | wasted render work | `react-render-proof` | +| Production error spike, latency change, or a metric that moved | production signal | `sentry-grafana-cross-ref` | +| Extension-specific: MV3 vs MV2, background vs UI context, service-worker lifecycle | platform | `extension-errors-debugging` | +| Runtime value disagrees with its declared type; green typecheck, wrong behaviour | type/reality drift | `typescript-compiler-blindspots` | +| Started after a dependency change; new capability or transitive edge | supply chain | `supply-chain-audit` | +| None of the above, or several | — | bisect to a change first, then re-classify | + +## The evidence bar carries over + +The engines are shared with `pr-validate`, and so are its trust gates. They matter more here, +because in review a weak instrument produces a weak claim someone else will challenge — in +debugging it produces a wrong theory nobody checks. + +- **An instrument that cannot fail is not evidence.** Before trusting a measurement, establish + it can report the negative: a positive control that must move, a base arm that must fail. +- **A null needs its sensitivity stated.** "No difference" and "could not have detected one" + print identically. Calibrate, then report the zero against what the instrument demonstrably + resolves. +- **Scope to the change.** Classify each finding as introduced-here versus pre-existing. + Report pre-existing separately and uncharged, or you will attribute an old defect to a new + diff. +- **A negative result carries the scope of its search.** "No leak found", "nothing in the logs", + "the artifact does not exist" are claims about where you looked. Name the stores searched in the + finding itself — filesystem, artifact bucket, issue tracker, the other process's logs. If you + cannot name them, the search is not finished. +- **Measure on an isolated machine.** Timing- and GC-sensitive numbers taken on a contended host + are not noisy-but-usable, they are *stably wrong* — several runs will agree with each other and + disagree with reality. Replicate across hosts, not just across runs, before trusting a figure. +- **Collect the whole battery, not the discriminating member.** Instruments that stay flat are + data: the joint pattern localises the defect in a way no single reading does. + +## Output + +A short investigation record, not a narrative: + +``` +SYMPTOM observation, as measured +CLASS defect class, and why (with the classes considered and dropped) +HYPOTHESES each with the observation that would kill it, and whether that was found +CAUSE located mechanism, at file:line — or "class excluded", which is a real result +NOT CAUSE hypotheses killed, kept so the next person does not re-walk them +``` + +Killed hypotheses are part of the deliverable. Deleting them makes the surviving one look +inevitable and hands the next investigator the same dead ends. + +## Scope — what this is NOT + +- Not a fix. It locates and evidences the cause; the change is a separate act. +- Not a replacement for the engines. Each owns its method; this chooses among them. +- Not an incident-management process. No severity, comms, or timeline. From 0558f9e11b4a36af3bb39385c6484946b48b4397 Mon Sep 17 00:00:00 2001 From: Jongsun Suh Date: Mon, 3 Aug 2026 08:16:26 -0400 Subject: [PATCH 2/3] Point the engine table at the renamed skills --- domains/pr-workflow/skills/debug/skill.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/domains/pr-workflow/skills/debug/skill.md b/domains/pr-workflow/skills/debug/skill.md index 556a1b7..1a6458a 100644 --- a/domains/pr-workflow/skills/debug/skill.md +++ b/domains/pr-workflow/skills/debug/skill.md @@ -1,12 +1,12 @@ --- name: debug -description: Locate the cause of a symptom you cannot yet explain — a crash, a leak, a flake, a production error spike, a number that moved. The sibling of pr-validate: where pr-validate is handed a claim and looks for the observation that would falsify it, this is handed a symptom and must generate the hypothesis first, then kill it. Classifies the symptom into a defect class, routes to the engine skill that owns that class (memory-leak-hunt, race-condition-proof, react-render-proof, sentry-grafana-cross-ref, extension-errors-debugging, typescript-compiler-blindspots, supply-chain-audit), and holds the investigation to the same evidence bar pr-validate applies — an instrument that cannot fail is not evidence, a null needs its sensitivity stated, and a finding is scoped to what the change introduced versus what pre-existed. Stops when the cause is located or the class is excluded, not when a plausible story is available. Triggers on /debug, or when asked to debug, diagnose, or investigate a symptom, find why something is slow, leaking, flaky, or erroring, chase a production alert to its cause, or reproduce a bug that cannot be reproduced by hand. +description: Locate the cause of a symptom you cannot yet explain — a crash, a leak, a flake, a production error spike, a number that moved. The sibling of evidence: where evidence is handed a claim and looks for the observation that would falsify it, this is handed a symptom and must generate the hypothesis first, then kill it. Classifies the symptom into a defect class, routes to the engine skill that owns that class (memory-leak, race-condition-repro, react-render-proof, sentry-grafana-correlation, extension-errors-debugging, tsc-blindspots, supply-chain-audit), and holds the investigation to the same evidence bar evidence applies — an instrument that cannot fail is not evidence, a null needs its sensitivity stated, and a finding is scoped to what the change introduced versus what pre-existed. Stops when the cause is located or the class is excluded, not when a plausible story is available. Triggers on /debug, or when asked to debug, diagnose, or investigate a symptom, find why something is slow, leaking, flaky, or erroring, chase a production alert to its cause, or reproduce a bug that cannot be reproduced by hand. maturity: experimental --- # /debug -`pr-validate` is given a claim and looks for the observation that would prove it false. +`evidence` is given a claim and looks for the observation that would prove it false. This is given a **symptom** and has to produce the hypothesis before anything can falsify it. That difference is the whole skill. In review, the claim is someone else's and the social @@ -23,8 +23,8 @@ first theory that fit the first observation. ## Do Not Use When -- The PR states a claim and you need it settled — that is `/pr-validate`. -- The cause is known and you are validating the fix — that is `/pr-validate`, or the engine +- The PR states a claim and you need it settled — that is `/evidence`. +- The cause is known and you are validating the fix — that is `/evidence`, or the engine skill directly. - You want an after-the-fact writeup of a resolved failure — that is a postmortem, not this. @@ -46,18 +46,18 @@ first theory that fit the first observation. | Symptom | Class | Engine | |---|---|---| -| Memory grows across a repeated flow; tab or worker dies over time | retention | `memory-leak-hunt` | -| Intermittent failure; passes on rerun; order-dependent | interleaving | `race-condition-proof` | +| Memory grows across a repeated flow; tab or worker dies over time | retention | `memory-leak` | +| Intermittent failure; passes on rerun; order-dependent | interleaving | `race-condition-repro` | | UI janks, re-renders excessively, selector recomputes | wasted render work | `react-render-proof` | -| Production error spike, latency change, or a metric that moved | production signal | `sentry-grafana-cross-ref` | +| Production error spike, latency change, or a metric that moved | production signal | `sentry-grafana-correlation` | | Extension-specific: MV3 vs MV2, background vs UI context, service-worker lifecycle | platform | `extension-errors-debugging` | -| Runtime value disagrees with its declared type; green typecheck, wrong behaviour | type/reality drift | `typescript-compiler-blindspots` | +| Runtime value disagrees with its declared type; green typecheck, wrong behaviour | type/reality drift | `tsc-blindspots` | | Started after a dependency change; new capability or transitive edge | supply chain | `supply-chain-audit` | | None of the above, or several | — | bisect to a change first, then re-classify | ## The evidence bar carries over -The engines are shared with `pr-validate`, and so are its trust gates. They matter more here, +The engines are shared with `evidence`, and so are its trust gates. They matter more here, because in review a weak instrument produces a weak claim someone else will challenge — in debugging it produces a wrong theory nobody checks. From ea4f5018bbc04a7dc3c78340f92a3fb015bc6aea Mon Sep 17 00:00:00 2001 From: Jongsun Suh Date: Tue, 4 Aug 2026 08:00:58 -0400 Subject: [PATCH 3/3] Name the installed command in `debug`'s description The installer emits `mms-debug`; the description advertised `/debug`. --- domains/pr-workflow/skills/debug/skill.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/domains/pr-workflow/skills/debug/skill.md b/domains/pr-workflow/skills/debug/skill.md index 1a6458a..2a35b42 100644 --- a/domains/pr-workflow/skills/debug/skill.md +++ b/domains/pr-workflow/skills/debug/skill.md @@ -1,6 +1,6 @@ --- name: debug -description: Locate the cause of a symptom you cannot yet explain — a crash, a leak, a flake, a production error spike, a number that moved. The sibling of evidence: where evidence is handed a claim and looks for the observation that would falsify it, this is handed a symptom and must generate the hypothesis first, then kill it. Classifies the symptom into a defect class, routes to the engine skill that owns that class (memory-leak, race-condition-repro, react-render-proof, sentry-grafana-correlation, extension-errors-debugging, tsc-blindspots, supply-chain-audit), and holds the investigation to the same evidence bar evidence applies — an instrument that cannot fail is not evidence, a null needs its sensitivity stated, and a finding is scoped to what the change introduced versus what pre-existed. Stops when the cause is located or the class is excluded, not when a plausible story is available. Triggers on /debug, or when asked to debug, diagnose, or investigate a symptom, find why something is slow, leaking, flaky, or erroring, chase a production alert to its cause, or reproduce a bug that cannot be reproduced by hand. +description: Locate the cause of a symptom you cannot yet explain — a crash, a leak, a flake, a production error spike, a number that moved. The sibling of evidence: where evidence is handed a claim and looks for the observation that would falsify it, this is handed a symptom and must generate the hypothesis first, then kill it. Classifies the symptom into a defect class, routes to the engine skill that owns that class (memory-leak, race-condition-repro, react-render-proof, sentry-grafana-correlation, extension-errors-debugging, tsc-blindspots, supply-chain-audit), and holds the investigation to the same evidence bar evidence applies — an instrument that cannot fail is not evidence, a null needs its sensitivity stated, and a finding is scoped to what the change introduced versus what pre-existed. Stops when the cause is located or the class is excluded, not when a plausible story is available. Triggers on /mms-debug, or when asked to debug, diagnose, or investigate a symptom, find why something is slow, leaking, flaky, or erroring, chase a production alert to its cause, or reproduce a bug that cannot be reproduced by hand. maturity: experimental ---