{
  "instructions": [
    {
      "instruction": "Always use Declarative Pipeline syntax for new pipelines (`pipeline { agent any stages { ... } }`); never use Scripted Pipeline syntax (`node { ... }`) for new work.",
      "original_snippets": "NEVER use Scripted Pipeline for new work... BAD: New pipelines starting with `node { ... }`. GOOD: Start with `pipeline { agent any stages { ... } }` Declarative syntax.",
      "relevant_when": "When generating any new Jenkinsfile pipeline",
      "why_given": "particular preference"
    },
    {
      "instruction": "Never store credentials as plain-text pipeline parameters; always use the Jenkins Credentials Store via `withCredentials` or the `credentials()` binding in the environment block.",
      "original_snippets": "NEVER store credentials as plain text pipeline parameters... BAD: `parameters { string(name: 'API_KEY', ...) }`... GOOD: `withCredentials([string(credentialsId: 'api-key-prod', variable: 'API_KEY')]) { ... }`",
      "relevant_when": "When the pipeline needs to use secrets, API keys, passwords, or tokens",
      "why_given": "new knowledge"
    },
    {
      "instruction": "Always add `parallelsAlwaysFailFast()` in the pipeline `options {}` block when using parallel or matrix blocks.",
      "original_snippets": "Always add `parallelsAlwaysFailFast()` in options when using parallel blocks... Always add `parallelsAlwaysFailFast()` to pipeline `options {}` block — covers all parallel/matrix blocks automatically.",
      "relevant_when": "When generating a Jenkinsfile that includes parallel stages or a matrix block",
      "why_given": "new knowledge"
    },
    {
      "instruction": "Always include `fingerprint: true` when using `archiveArtifacts` for build traceability.",
      "original_snippets": "Always include `fingerprint: true` when using `archiveArtifacts`... success { archiveArtifacts artifacts: '**/*.jar', fingerprint: true }",
      "relevant_when": "When generating a pipeline that archives build artifacts",
      "why_given": "new knowledge"
    },
    {
      "instruction": "Always include a `post { always { cleanWs() } }` block in every Declarative pipeline.",
      "original_snippets": "NEVER omit `post { always { cleanWs() } }`... BAD: No `post` block in the pipeline. GOOD: `post { always { cleanWs() } }` in every Declarative pipeline.",
      "relevant_when": "When generating any Declarative Jenkinsfile",
      "why_given": "new knowledge"
    },
    {
      "instruction": "Use single-quote shell strings with `withCredentials` to prevent Groovy string expansion of secrets: `sh 'curl -H \"Authorization: Bearer $API_KEY\"'` (single quotes prevent Groovy interpolation; the credential is still available via the shell environment).",
      "original_snippets": "NEVER call `sh` with inline secret variable expansion... BAD: `sh \"curl -H 'Authorization: Bearer ${API_KEY}'\"`... GOOD: `withCredentials([...]) { sh 'curl -H \"Authorization: Bearer $API_KEY\"' }` (single quotes prevent Groovy expansion)",
      "relevant_when": "When writing shell steps that reference credential variables",
      "why_given": "new knowledge"
    },
    {
      "instruction": "Extract independent stages (lint, unit-test, integration-test, SAST) into `parallel { }` blocks instead of sequential stages.",
      "original_snippets": "NEVER run all stages on a heavyweight executor without parallelism... BAD: Lint, unit-test, integration-test, and SAST in sequential stages. GOOD: Wrap independent stages in `parallel { stage('Lint') { ... } stage('Unit Test') { ... } }`.",
      "relevant_when": "When generating pipelines with multiple independent testing or checking stages",
      "why_given": "particular preference"
    },
    {
      "instruction": "Include `timeout`, `buildDiscarder`, `timestamps`, and `disableConcurrentBuilds` in the pipeline `options {}` block.",
      "original_snippets": "Options: timeout, buildDiscarder, timestamps, disableConcurrentBuilds\noptions {\n    buildDiscarder(logRotator(numToKeepStr: '10'))\n    timeout(time: 1, unit: 'HOURS')\n    disableConcurrentBuilds()\n    timestamps()\n}",
      "relevant_when": "When generating any Declarative Jenkinsfile",
      "why_given": "reminder"
    },
    {
      "instruction": "Use `beforeAgent true` on `when` conditions to skip agent allocation if the condition fails.",
      "original_snippets": "Add `beforeAgent true` to skip agent allocation if condition fails.",
      "relevant_when": "When generating conditional stages that use a `when {}` block",
      "why_given": "new knowledge"
    },
    {
      "instruction": "Place `input` outside `steps {}` to avoid holding agents during manual approval.",
      "original_snippets": "Place `input` outside steps to avoid holding agents.",
      "relevant_when": "When generating a pipeline with a manual approval or input step",
      "why_given": "new knowledge"
    },
    {
      "instruction": "Use `catchError(buildResult: 'UNSTABLE', stageResult: 'FAILURE')` or `warnError` for error-tolerant stages rather than failing the entire build.",
      "original_snippets": "catchError(buildResult: 'UNSTABLE', stageResult: 'FAILURE') { sh '...' }\nwarnError('msg') { sh '...' }",
      "relevant_when": "When generating pipelines with flaky or optional stages that should not fail the whole build",
      "why_given": "new knowledge"
    },
    {
      "instruction": "Use `@NonCPS` annotation for non-serializable operations (JsonSlurper, iterators, regex Matchers) in Scripted pipelines; do not include pipeline steps inside a `@NonCPS` method.",
      "original_snippets": "@NonCPS\ndef parseJson(String json) {\n    new groovy.json.JsonSlurper().parseText(json)\n}\nRequired for non-serializable operations (JsonSlurper, iterators, regex Matchers). No pipeline steps inside.",
      "relevant_when": "When generating Scripted pipeline methods that use non-serializable Groovy constructs",
      "why_given": "new knowledge"
    },
    {
      "instruction": "Use `python3 scripts/generate_declarative.py` for generating simple standard Declarative pipelines; use `python3 scripts/generate_scripted.py` for simple Scripted pipelines; use `python3 scripts/generate_shared_library.py` for shared library scaffolding.",
      "original_snippets": "python3 scripts/generate_declarative.py --output Jenkinsfile --stages build,test,deploy --agent docker\npython3 scripts/generate_scripted.py --output Jenkinsfile --stages build,test --agent label:linux\npython3 scripts/generate_shared_library.py --name my-library --package com.example",
      "relevant_when": "When generating a simple standard pipeline or shared library scaffold",
      "why_given": "particular preference"
    },
    {
      "instruction": "Always validate the generated Jenkinsfile using `devops-skills:jenkinsfile-validator` and then handle results: fix ERRORS, should fix WARNINGS, apply INFO optimisations based on use case; re-validate after fixes.",
      "original_snippets": "ALWAYS validate using devops-skills:jenkinsfile-validator skill... Handle validation results by severity: ERRORS: Must fix... WARNINGS: Should fix... INFO: Apply optimizations... Re-validate after fixes",
      "relevant_when": "After generating any Jenkinsfile",
      "why_given": "reminder"
    },
    {
      "instruction": "Consult `assets/templates/declarative/basic.Jenkinsfile` and `references/best_practices.md` before generating a Declarative pipeline.",
      "original_snippets": "Consult `assets/templates/declarative/basic.Jenkinsfile` and `references/best_practices.md`",
      "relevant_when": "When starting to generate a Declarative pipeline",
      "why_given": "particular preference"
    },
    {
      "instruction": "Use `withCredentials` with credentials binding for secrets in both Declarative and Scripted pipelines.",
      "original_snippets": "withCredentials([string(credentialsId: 'key', variable: 'KEY')]) { sh 'curl -H \"Auth: $KEY\" ...' }",
      "relevant_when": "Whenever a shell step needs to use a secret value",
      "why_given": "reminder"
    },
    {
      "instruction": "Consult external plugin documentation for plugins not covered in `references/common_plugins.md` or for version-specific or complex configurations; skip lookup for basic well-documented steps.",
      "original_snippets": "Always consult external docs for: Plugins NOT in `references/common_plugins.md`... Skip external lookup when: Using basic syntax from `references/common_plugins.md`",
      "relevant_when": "When the pipeline uses a plugin that is not one of the standard covered plugins",
      "why_given": "reminder"
    },
    {
      "instruction": "Add SonarQube, OWASP Dependency-Check, or Trivy stages with fail thresholds for DevSecOps pipelines.",
      "original_snippets": "Add SonarQube, OWASP Dependency-Check, Trivy stages with fail thresholds.",
      "relevant_when": "When generating a pipeline that requires security scanning",
      "why_given": "reminder"
    },
    {
      "instruction": "Use `durabilityHint('PERFORMANCE_OPTIMIZED')` in options for simple pipelines to achieve 2-6x faster execution.",
      "original_snippets": "durabilityHint('PERFORMANCE_OPTIMIZED')  // 2-6x faster for simple pipelines",
      "relevant_when": "When generating simple pipelines where durability is not a primary concern",
      "why_given": "new knowledge"
    },
    {
      "instruction": "Use `matrix {}` with `axes {}` for multi-dimensional builds across platforms or browsers.",
      "original_snippets": "Use `parallel {}` or `matrix {}` with `axes {}` for multi-dimensional builds.\nstage('Matrix') {\n    matrix {\n        axes {\n            axis { name 'PLATFORM'; values 'linux', 'windows' }",
      "relevant_when": "When generating a pipeline that needs to test across multiple OS, language version, or browser combinations",
      "why_given": "new knowledge"
    }
  ]
}