apiVersion: devrunbook.io/v1alpha1 kind: Playbook metadata: id: bugfix.root-cause slug: root-cause-bugfix version: 1.0.0 title: Root-Cause Bug Fix summary: Reproduce a defect, identify its root cause, add regression evidence and implement the smallest structural repair. category: bugfixing tags: - bugfix - root-cause - regression lifecycle: reviewed riskTier: moderate authors: - name: DevRunbook Core Team license: MIT package: files: - path: prompt.md role: template digest: true exportByDefault: false - path: README.md role: documentation digest: true exportByDefault: false - path: CHANGELOG.md role: changelog digest: true exportByDefault: false - path: examples/minimal.yaml role: example digest: true exportByDefault: false - path: evaluations/static-structure.yaml role: evaluation digest: true exportByDefault: false spec: type: guided intent: problem: A reported defect can be patched superficially without proving the true cause, preserving the failure as a future regression. outcome: Reproduce the defect, identify the smallest structural root cause, add regression evidence and verify the repair across relevant checks. whenToUse: - A specific bug or regression is observable. - A failing test, error, incorrect flow or reproducible symptom exists. whenNotToUse: - Requirements are primarily a new feature request. - The environment needed to reproduce the issue is legally or operationally unavailable. modes: - guided - execute - recovery defaultMode: execute autonomy: min: diagnose max: repair default: verify inputs: - key: problemStatement label: Problem statement description: Describe the observed behavior, expected behavior and user impact. type: multiline required: true sensitive: false includeInOutput: true - key: reproductionClues label: Reproduction clues description: Provide safe steps, errors or conditions already known. type: multiline required: false sensitive: false includeInOutput: true default: '' - key: preserveCompatibility label: Preserve backwards compatibility description: Require existing public behavior and interfaces to remain compatible. type: boolean required: true sensitive: false includeInOutput: true default: true - key: affectedScope label: Affected scope description: Optional files, modules or feature area believed to be involved. type: string-list required: false sensitive: false includeInOutput: true default: [] compatibility: repositoryRequired: true languages: [] frameworks: [] packageManagers: [] databases: [] deploymentTypes: [] requiredProfileCapabilities: - test-command incompatibleConditions: [] guardrails: - id: reproduce-first severity: blocking text: Do not change production logic until the issue is reproduced or a bounded evidence-based explanation shows why reproduction is unavailable. - id: no-test-weakening severity: blocking text: Do not delete, skip or weaken tests and checks merely to obtain a passing result. - id: minimal-causal-fix severity: blocking text: Keep the implementation focused on the root cause and avoid unrelated cleanup. - id: protect-behavior severity: blocking text: Preserve existing documented behavior and public contracts unless the problem statement explicitly changes them. workflow: - id: read-rules title: Read repository guidance instruction: Inspect AGENTS.md, relevant documentation and test/build configuration before modifying files. required: true - id: reproduce title: Reproduce the defect instruction: Use the narrowest existing command or create a focused failing regression test that demonstrates the observed defect. required: true - id: trace title: Identify root cause instruction: Trace the failing behavior across relevant boundaries and distinguish cause from downstream symptoms. required: true - id: implement title: Implement structural repair instruction: Apply the smallest maintainable change that fixes the cause while preserving unrelated behavior. required: true - id: validate-targeted title: Run targeted validation instruction: Run the regression test and directly relevant tests immediately. required: true - id: validate-full title: Run declared validation instruction: Run available lint, typecheck, test and build roles appropriate to the changed scope. required: true - id: review-diff title: Review final diff instruction: Remove accidental changes and confirm protected paths and public contracts remain intact. required: true validation: commandRoles: - lint - typecheck - unit-test - integration-test - build checks: - id: reproduction type: assertion description: The defect is demonstrated before the production fix or inability is explicitly evidenced. blocking: true evidence: Failing test, command output or bounded reproduction report. - id: regression type: artifact description: A regression check covers the root cause where feasible. blocking: true evidence: New or updated test and result. - id: targeted type: command description: Directly relevant validation passes after the fix. blocking: true evidence: Command and exit result. - id: full type: command description: All available required repository validation roles pass or genuine unrelated failures are identified. blocking: true evidence: Command summary. - id: scope type: assertion description: Final diff contains no unexplained unrelated changes. blocking: true evidence: Changed-file review. completion: criteria: - Observed defect is fixed at the root cause. - Regression evidence demonstrates the prior failure and repaired behavior. - Relevant lint, typecheck, tests and build pass. - Compatibility and protected paths remain intact. - Unresolved environmental or unrelated failures are reported honestly. failurePolicy: onValidationFailure: Investigate failures caused by the current work, repair them when they remain within scope, rerun the affected validation and report any genuine blocker without claiming success. onAmbiguity: Use repository evidence and existing conventions for minor choices. For material product ambiguity, preserve current behavior, document the decision needed and stop before an irreversible change. onMissingContext: Inspect the repository for the missing non-sensitive context. Never invent commands, credentials, production behavior or validation results. Report what remains unavailable. onOutOfScopeCause: Explain the evidenced out-of-scope cause, avoid broad unrelated changes and provide the smallest safe follow-up recommendation. onExternalDependencyUnavailable: Use a safe local fixture only when it preserves the behavior under test. Otherwise report the blocked validation and do not claim the external path succeeded. onUnableToReproduce: Record attempted reproduction and environment evidence. Do not make speculative production changes; provide the narrowest next diagnostic action. reporting: sections: - id: root-cause title: Root cause required: true description: Explain the actual cause and why the previous behavior occurred. - id: changes title: Changes required: true description: List changed files and the purpose of each change. - id: validation title: Validation required: true description: List commands/checks and outcomes, including pre-fix reproduction. - id: risk title: Risk and compatibility required: true description: State compatibility impact, remaining risk and untested conditions. - id: unresolved title: Unresolved items required: true description: State genuine blockers or unrelated failures; write None when empty. template: main: prompt.md partials: [] exports: prompt: true markdown: true runPack: false agentsSuggestion: false quality: reviewStatus: technical-reviewed testedStacks: [] knownLimitations: - Some production-only defects may require a safe synthetic reproduction rather than direct access. evaluationCaseIds: - root-cause-bugfix.static-structure