apiVersion: devrunbook.io/v1alpha1
kind: Playbook
metadata:
  id: ${category}.${logical-id}
  slug: ${slug}
  version: 0.1.0
  title: ${Title}
  summary: ${A concise summary of the problem and outcome.}
  category: ${category}
  tags: [${tag}]
  lifecycle: draft
  riskTier: moderate
  authors:
    - name: ${Author}
  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: ${Describe the failure mode this playbook prevents.}
    outcome: ${Describe the observable result.}
    whenToUse: [${Use case}]
    whenNotToUse: [${Exclusion}]
  modes: [inspect, plan]
  defaultMode: plan
  autonomy: {min: observe, max: plan, default: plan}
  inputs:
    - key: taskContext
      label: Task context
      description: ${Describe the required user context.}
      type: multiline
      required: true
      sensitive: false
      includeInOutput: true
  compatibility:
    repositoryRequired: true
    languages: []
    frameworks: []
    packageManagers: []
    databases: []
    deploymentTypes: []
    requiredProfileCapabilities: []
    incompatibleConditions: []
  guardrails:
    - id: bounded-scope
      severity: blocking
      text: Keep investigation and recommendations within the declared task scope.
  workflow:
    - id: inspect
      title: Inspect relevant evidence
      instruction: Read repository guidance and gather bounded evidence before conclusions.
      required: true
  validation:
    commandRoles: []
    checks:
      - id: evidence
        type: assertion
        description: Every material conclusion references evidence or an explicit unknown.
        blocking: true
        evidence: Final evidence table.
  completion:
    criteria: [The requested outcome is evidenced and remaining uncertainty is explicit.]
  failurePolicy:
    onValidationFailure: Report the failed check, preserve evidence and do not claim completion.
    onAmbiguity: State the narrowest safe assumption and record its effect on the result.
    onMissingContext: Continue only with bounded inspection and identify the missing context.
    onOutOfScopeCause: Document the cause and propose a separate scoped follow-up task.
    onExternalDependencyUnavailable: Use available local evidence and mark external checks as not run.
    onUnableToReproduce: Preserve reproduction evidence and report the smallest next diagnostic step.
  reporting:
    sections:
      - id: summary
        title: Summary
        required: true
      - id: evidence
        title: Evidence and validation
        required: true
  template:
    main: prompt.md
    partials: []
  exports:
    prompt: true
    markdown: true
    runPack: true
    agentsSuggestion: false
quality:
  reviewStatus: unreviewed
  testedStacks: []
  knownLimitations: [This draft has not yet been evaluated on a fixture repository.]
  evaluationCaseIds: [${slug}.static-structure]