Recipe catalog / feedback-actionability

Grade feedback actionability

How actionable is feedback for its recipient, on a five-level rubric from no direction to a specific change with reason and example?

You review teacher comments, code review notes, or peer feedback before delivery and want to flag items the recipient could not act on.

Explore this recipe interactively · Source and implementation guide

Use feedback-actionability in TypeScript

Install with npm install jev-recipes. Requires Node.js 22.9 or newer and ES modules. Set TYPESAFE_API_KEY in your server environment for live calls, which send input to TypeSafe and use API quota. See the installation guide.

import { feedbackActionability } from 'jev-recipes/feedback-actionability';

const result = await feedbackActionability({
  "feedback": "Your introduction buries the thesis in the fourth sentence, so a reader does not know what you are arguing until the paragraph is almost over. Move the thesis to the first or second sentence. For example, open with 'Remote work raised productivity for knowledge workers but widened the gap for new hires,' then use the rest of the paragraph to preview your three sections.",
  "minConfidence": 0.8
});
console.log(result);

Input contract

{
  "input": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "feedback": {
        "type": "string"
      },
      "minConfidence": {
        "type": "number",
        "minimum": 0,
        "maximum": 1
      }
    },
    "required": [
      "feedback"
    ]
  },
  "result": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "model": {
        "type": "string"
      },
      "usage": {
        "type": "object",
        "properties": {
          "input_tokens": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "output_tokens": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "input_tokens",
          "output_tokens"
        ],
        "additionalProperties": false
      },
      "status": {
        "type": "string",
        "enum": [
          "ready",
          "review"
        ]
      },
      "score": {
        "type": "number",
        "minimum": 0
      },
      "level": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991
      },
      "confidence": {
        "type": "number",
        "minimum": 0,
        "maximum": 1
      },
      "probabilities": {
        "type": "object",
        "propertyNames": {
          "type": "string"
        },
        "additionalProperties": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        }
      },
      "actionability": {
        "type": "string",
        "enum": [
          "none",
          "vague",
          "directional",
          "specific",
          "complete"
        ]
      }
    },
    "required": [
      "model",
      "usage",
      "status",
      "score",
      "level",
      "confidence",
      "probabilities",
      "actionability"
    ],
    "additionalProperties": false
  }
}

Saved example result

This hand-authored response demonstrates the contract. It is not a model accuracy measurement. Run it without an API key: npx jev-recipes demo feedback-actionability.

{
  "model": "demo-fixture",
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0
  },
  "status": "ready",
  "score": 3.84,
  "level": 4,
  "confidence": 0.88,
  "probabilities": {
    "0": 0,
    "1": 0.01,
    "2": 0.02,
    "3": 0.09,
    "4": 0.88
  },
  "actionability": "complete"
}

Evaluation evidence

Use the evaluation guide to measure this decision on your own labeled cases.

Limitations

• Grades clarity of direction, not whether the advice is correct or appropriate.
• Judges the feedback text alone; it cannot see the work being reviewed.
• The score is an expected value over levels. Application code chooses cutoffs.

Related recipes

• requirement-testability: Use requirement-testability to check whether a stated requirement can be verified.
• tone-check: Use tone-check to judge the wording of the same feedback against writing criteria.