Publish DevRunbook source

content/playbooks/root-cause-bugfix/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 1.0.0
+
+- Initial reviewed example package for **Root-Cause Bug Fix**.

content/playbooks/root-cause-bugfix/README.md

@@ -0,0 +1,5 @@
+# Root-Cause Bug Fix
+
+Reproduce a defect, identify its root cause, add regression evidence and implement the smallest structural repair.
+
+This package is a normative DevRunbook example. Validate it against `schemas/playbook.schema.json`.

content/playbooks/root-cause-bugfix/evaluations/static-structure.yaml

@@ -0,0 +1,23 @@
+apiVersion: devrunbook.io/v1alpha1
+kind: EvaluationCase
+metadata:
+  id: root-cause-bugfix.static-structure
+  version: 1.0.0
+spec:
+  playbookVersion: 1.0.0
+  inputFile: ../examples/minimal.yaml
+  expectedHeadings:
+  - Mission
+  - Scope
+  - Constraints and guardrails
+  - Execution workflow
+  - Validation plan
+  - Completion contract
+  - Final reporting format
+  prohibitedPatterns:
+  - BEGIN PRIVATE KEY
+  - 'Authorization: Bearer'
+  deterministic: true
+  requiredPatterns:
+  - Root-Cause Bug Fix
+  expectedLintStatus: ready

content/playbooks/root-cause-bugfix/examples/minimal.yaml

@@ -0,0 +1,10 @@
+playbook:
+  slug: root-cause-bugfix
+  version: 1.0.0
+workMode: guided
+autonomyLevel: verify
+inputs:
+  problemStatement: Example value for Problem statement
+  reproductionClues: ''
+  preserveCompatibility: true
+  affectedScope: []

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

@@ -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

content/playbooks/root-cause-bugfix/prompt.md

@@ -0,0 +1,14 @@
+# Root-cause bug-fix instructions
+
+Problem to solve:
+
+{{ inputs.problemStatement }}
+
+Known reproduction clues:
+
+{{ inputs.reproductionClues }}
+
+Likely affected scope: {{ inputs.affectedScope }}.
+Backwards compatibility required: {{ inputs.preserveCompatibility }}.
+
+Begin with evidence. Do not anchor on the user's suspected module if repository behavior points elsewhere. A new regression test should fail for the correct reason before the fix and pass afterward. Do not make unrelated style or dependency changes unless they are strictly necessary for the causal repair and are explained.