DevRunbook-Public/content/playbooks/root-cause-bugfix/playbook.yaml

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