why.diagnose

{
  "additionalProperties": false,
  "description": "What a reader recognised, as a comma-separated list of names.\n\nA name is a signal id or a moment id: a person ticking symptoms and a script naming\nmoments reach the same answer, because a signal resolves to the moment that owns it.\nThe parameter is one string rather than a list because a diagnosis changes nothing and\nis therefore a `GET`, and this repository binds a `GET` input to the query string.",
  "properties": {
    "signals": {
      "default": "",
      "description": "Signal ids or moment ids, separated by commas. Empty selects nothing and is\nanswered with an empty diagnosis rather than an error.",
      "type": "string"
    }
  },
  "title": "DiagnoseInput",
  "type": "object"
}

{
  "$defs": {
    "Recommendation": {
      "description": "One recommendation, with the moments that produced it. A recommendation with no\n`matched_because` is a recommendation nobody can check.",
      "properties": {
        "count": {
          "description": "How many of the selected moments name it.",
          "format": "uint",
          "minimum": 0,
          "type": "integer"
        },
        "id": {
          "description": "The thing recommended: a capability id, a command, a claim, a rule, a use case.",
          "type": "string"
        },
        "matched_because": {
          "description": "The selected moments that named it, in presentation order.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "required": [
        "id",
        "count",
        "matched_because"
      ],
      "type": "object"
    }
  },
  "description": "What a reader's selection implies, computed by counting rather than by inference.\n\nThe arithmetic is the whole model and is stated so a reader can check it: a selection\nresolves to a set of moments; an area or an audience scores the number of selected\nmoments that name it; a recommendation scores the number that name it and carries\ntheir ids. There is no weighting and no percentage, because there is no model behind\none.",
  "properties": {
    "also_worth_reading": {
      "description": "Moments the selection did not include that share an area with one that it did.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "areas": {
      "description": "Operational areas by how many selected moments fall under them, heaviest first.",
      "items": {
        "$ref": "#/$defs/Recommendation"
      },
      "type": "array"
    },
    "audiences": {
      "description": "Audiences by how many selected moments they recognise, heaviest first.",
      "items": {
        "$ref": "#/$defs/Recommendation"
      },
      "type": "array"
    },
    "capabilities": {
      "description": "Capabilities of the executable that answer the selected moments.",
      "items": {
        "$ref": "#/$defs/Recommendation"
      },
      "type": "array"
    },
    "claims": {
      "description": "Claims that say what is guaranteed.",
      "items": {
        "$ref": "#/$defs/Recommendation"
      },
      "type": "array"
    },
    "commands": {
      "description": "Commands that answer them.",
      "items": {
        "$ref": "#/$defs/Recommendation"
      },
      "type": "array"
    },
    "doctrines": {
      "description": "Rules of the effective set that govern them.",
      "items": {
        "$ref": "#/$defs/Recommendation"
      },
      "type": "array"
    },
    "moments": {
      "description": "The moments the selection resolved to, in presentation order.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "unresolved": {
      "description": "Selected names that resolved to nothing.",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "use_cases": {
      "description": "Use cases that show the way out.",
      "items": {
        "$ref": "#/$defs/Recommendation"
      },
      "type": "array"
    }
  },
  "required": [
    "moments",
    "unresolved",
    "areas",
    "audiences",
    "capabilities",
    "commands",
    "claims",
    "doctrines",
    "use_cases",
    "also_worth_reading"
  ],
  "title": "Diagnosis",
  "type": "object"
}