|
|
|
@@ -0,0 +1,238 @@
|
|
|
|
|
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
|
DevRunbook release export