Activation Contract
Load when auditing a defect backlog for shared root causes, proposing a fix for an issue cluster, or closing issues as resolved/outdated. Complements rdd-defect-workflow (single-defect flow) — this skill governs the cluster-level method.
Hard Rules
- Read full bodies and comments, never titles. Classify against the actual code or PR diff, not descriptions of it.
- Verify every "fixed" or "broken" claim against current
origin/main the day you act. Compare report dates to fix merge dates: a repro filed before the fix landed is evidence about old builds, not current code.
- Cluster defects by causal root, not surface. Each root gets a measured row in the meta-issue (#2471 style): issues attached, fix shape, state.
- Before proposing any fix, produce a read-only mechanism map: one file:line anchor per claim, mechanism explained as implemented today. Report claim-vs-code mismatches explicitly; never force evidence to fit the hypothesis. Let the map shrink the proposal.
- Rank solutions by what they DELETE: (1) removes a mechanism so the class becomes impossible, (2) static guard-ratchet making reintroduction a test failure, (3) localized predicate fix behind a failing repro test. New surface (verbs, flags, mechanisms) is last resort — defer until re-verified evidence demands it.
- Extract maintainer choices as named D-items with recommended defaults. A maintainer condition recorded in an issue thread outranks any plan table, including yours.
- Close only with evidence, one rule per closure: (A) fixed on main, cite commit AND proving test; (B) superseded by recorded maintainer decision; (C) surface no longer exists; (D) duplicate of a fixed issue. Comment before closing: what resolved it, verified today, reopen invitation. When in doubt, do not close — list as borderline.
- Clean break, never compatibility. When a format or identity changes, bump its versioned tag as a REPLACEMENT: old records become outdated and fail closed with an actionable refusal naming the rerun. Never write dual recognition, legacy fallbacks, or compat shims; that residue is what the deletion criterion exists to prevent. Stored bytes are never rewritten and stay readable for forensics, but carry no gate or lifecycle validity.
- Implementation follows the waves recipe: repro as failing test first, byte-stable goldens as defect signal, independently revertible slices, one writer per slice.
- A universal guard's verification matrix is
go test ./... at the repository root, never a curated package list. A guard that forbids a shape breaks every fixture that relied on it, including in packages the change never touched.
- One worktree per writer, always, including the orchestrator. Before editing inline, check whether a delegated worker holds that path; if so, create a separate worktree rather than reusing it.
- Audit every worker report yourself: re-run its key verification, decoy-test any new guard, spot-check its diffs. A self-report is a claim, not evidence.
Decision Gates
| Condition |
Action |
| Issue's failure mechanism absent from current main |
Re-verify on latest build; close by rule A/C or mark stale — never fix ghost code. |
| Fix would add a mechanism, flag, or verb |
Defer with written reason; re-rank for a deletion-shaped alternative first. |
| Map contradicts the issue or your hypothesis |
The map wins. Revise the plan and correct the public record (meta-issue) before coding. |
| Blocker's fix lives in an unmerged PR |
Leave open; it closes on merge or by its own thread condition. |
| Closure evidence incomplete |
Borderline list, not closure. |
Execution Steps
- Measure: read the cluster fully; partition by root; record counts in the meta-issue.
- Classify each issue against the real diff/code; separate closes-via-X, improved-not-closed, unrelated, blocker.
- Map mechanisms read-only with anchors; flag mismatches.
- Rank fixes deletion-first; name D-items; get maintainer answers.
- Implement in slices (issue-first: every PR links a
status:approved issue), audit each worker report.
- Hygiene pass: evidence-gated closures, stale-repro re-verification requests, meta-issue update with what changed and why.
Output Contract
Per pass, report: roots table (issues, fix shape, state), closures with rule+evidence, borderline list with reasons, D-items and their answers, mechanism-map mismatches found, and the meta-issue comment link.
References
../rdd-advisory-transport/references/shared-advisory-transport-proposal.md — exemplar proposal shape produced by this method.../rdd-advisory-transport/references/issue-impact-matrix.md — exemplar per-issue disposition matrix.
1---2name: issue-root-resolution3description: Trigger: root audit, atacar la raíz, issue roots, backlog roots, mechanism map, deletion-driven fix, resolver issues de raíz, close outdated issues. Audit and resolve issue clusters by verified root cause.4license: Apache-2.05---6
7## Activation Contract
8
9Load when auditing a defect backlog for shared root causes, proposing a fix for an issue cluster, or closing issues as resolved/outdated. Complements `rdd-defect-workflow` (single-defect flow) — this skill governs the cluster-level method.
10
11## Hard Rules
12
13- Read full bodies and comments, never titles. Classify against the actual code or PR diff, not descriptions of it.
14- Verify every "fixed" or "broken" claim against current `origin/main` the day you act. Compare report dates to fix merge dates: a repro filed before the fix landed is evidence about old builds, not current code.
15- Cluster defects by causal root, not surface. Each root gets a measured row in the meta-issue (#2471 style): issues attached, fix shape, state.
16- Before proposing any fix, produce a read-only mechanism map: one file:line anchor per claim, mechanism explained as implemented today. Report claim-vs-code mismatches explicitly; never force evidence to fit the hypothesis. Let the map shrink the proposal.
17- Rank solutions by what they DELETE: (1) removes a mechanism so the class becomes impossible, (2) static guard-ratchet making reintroduction a test failure, (3) localized predicate fix behind a failing repro test. New surface (verbs, flags, mechanisms) is last resort — defer until re-verified evidence demands it.
18- Extract maintainer choices as named D-items with recommended defaults. A maintainer condition recorded in an issue thread outranks any plan table, including yours.
19- Close only with evidence, one rule per closure: (A) fixed on main, cite commit AND proving test; (B) superseded by recorded maintainer decision; (C) surface no longer exists; (D) duplicate of a fixed issue. Comment before closing: what resolved it, verified today, reopen invitation. When in doubt, do not close — list as borderline.
20- Clean break, never compatibility. When a format or identity changes, bump its versioned tag as a REPLACEMENT: old records become outdated and fail closed with an actionable refusal naming the rerun. Never write dual recognition, legacy fallbacks, or compat shims; that residue is what the deletion criterion exists to prevent. Stored bytes are never rewritten and stay readable for forensics, but carry no gate or lifecycle validity.
21- Implementation follows the waves recipe: repro as failing test first, byte-stable goldens as defect signal, independently revertible slices, one writer per slice.
22- A universal guard's verification matrix is `go test ./...` at the repository root, never a curated package list. A guard that forbids a shape breaks every fixture that relied on it, including in packages the change never touched.
23- One worktree per writer, always, including the orchestrator. Before editing inline, check whether a delegated worker holds that path; if so, create a separate worktree rather than reusing it.
24- Audit every worker report yourself: re-run its key verification, decoy-test any new guard, spot-check its diffs. A self-report is a claim, not evidence.
25
26## Decision Gates
27
28| Condition | Action |
29| --- | --- |
30| Issue's failure mechanism absent from current main | Re-verify on latest build; close by rule A/C or mark stale — never fix ghost code. |
31| Fix would add a mechanism, flag, or verb | Defer with written reason; re-rank for a deletion-shaped alternative first. |
32| Map contradicts the issue or your hypothesis | The map wins. Revise the plan and correct the public record (meta-issue) before coding. |
33| Blocker's fix lives in an unmerged PR | Leave open; it closes on merge or by its own thread condition. |
34| Closure evidence incomplete | Borderline list, not closure. |
35
36## Execution Steps
37
381. Measure: read the cluster fully; partition by root; record counts in the meta-issue.
392. Classify each issue against the real diff/code; separate closes-via-X, improved-not-closed, unrelated, blocker.
403. Map mechanisms read-only with anchors; flag mismatches.
414. Rank fixes deletion-first; name D-items; get maintainer answers.
425. Implement in slices (issue-first: every PR links a `status:approved` issue), audit each worker report.
436. Hygiene pass: evidence-gated closures, stale-repro re-verification requests, meta-issue update with what changed and why.
44
45## Output Contract
46
47Per pass, report: roots table (issues, fix shape, state), closures with rule+evidence, borderline list with reasons, D-items and their answers, mechanism-map mismatches found, and the meta-issue comment link.
48
49## References
50
51- `../rdd-advisory-transport/references/shared-advisory-transport-proposal.md` — exemplar proposal shape produced by this method.
52- `../rdd-advisory-transport/references/issue-impact-matrix.md` — exemplar per-issue disposition matrix.
gabrielmoreira