createImprovement

{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "type": {
      "type": "string",
      "description": "Type. Default: enhancement. Valid values: feature, bug, tech_debt, architecture_gap, documentation_gap, risk, enhancement, task. Despite the tool's name there is no 'improvement' value — pass it and it is accepted as an alias for 'enhancement', which is also the default. Setting type='task' makes the row a task (TAS- prefix); any other type makes it a non-task improvement (IMP- prefix)."
    },
    "priority": {
      "type": "string",
      "description": "Priority. Default: medium."
    },
    "status": {
      "type": "string",
      "description": "Initial status. Default: captured."
    },
    "source": {
      "type": "string",
      "description": "Source (e.g. human_manual, agent_review)."
    },
    "urgency": {
      "type": "string",
      "description": "e.g. this_week, this_month, this_quarter."
    },
    "category_id": {
      "type": "string",
      "description": "Category ID."
    },
    "problem_statement": {
      "type": "string"
    },
    "desired_outcome": {
      "type": "string"
    },
    "business_impact": {
      "type": "string"
    },
    "user_impact": {
      "type": "string"
    },
    "why_now": {
      "type": "string"
    },
    "acceptance_criteria": {
      "type": "array",
      "description": "Acceptance criteria — ordered list of pass/fail statements that define \"done\" for this item. Each row is `{ id, text }` with server-stamped `updated_at / updated_by / updated_by_credential_name`. REPLACES the whole array on update. Echo back existing `id`s on rows you keep so attribution stamps survive. Bare strings are accepted for convenience (e.g. `[\"row 1\", \"row 2\"]`) and auto-converted to `{ id, text }`.",
      "items": {
        "anyOf": [
          {
            "type": "string",
            "description": "Shorthand for `{ text: \"...\" }`."
          },
          {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "description": "Optional — server mints one if omitted. Preserve on edits."
              },
              "text": {
                "type": "string"
              },
              "updated_at": {
                "type": "string",
                "description": "Server-stamped. Echo back unchanged; ignored on new rows."
              },
              "updated_by": {
                "type": "string",
                "description": "Server-stamped user id. Echo back unchanged."
              },
              "updated_by_credential_name": {
                "type": "string",
                "description": "Server-stamped credential label. Echo back unchanged."
              }
            },
            "required": [
              "text"
            ]
          }
        ]
      }
    },
    "checklist": {
      "type": "array",
      "description": "Tick-box checklist shown above acceptance_criteria. The full array REPLACES the stored list on update, and array order = display order — to edit, fetch via getTask/getImprovement, modify, and send back the whole list. Operations: mark done with `completed: true`; un-mark with `completed: false`; add rows by appending `{ text }` (id is auto-minted); remove by omitting; reorder by rearranging. Echo back each existing `id` you keep so per-row attribution (who added/completed it, when) survives.",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Optional — server mints one if omitted. Preserve on edits."
          },
          "text": {
            "type": "string"
          },
          "due_date": {
            "type": "string",
            "description": "Optional YYYY-MM-DD; null to clear."
          },
          "completed": {
            "type": "boolean",
            "description": "true = ticked, false/omitted = not done. Server stamps timestamp + actor."
          },
          "completed_at": {
            "type": "string",
            "description": "Server-stamped ISO timestamp. Prefer `completed`; an explicit value here wins if both are sent."
          },
          "completed_by": {
            "type": "string",
            "description": "Server-stamped user id. Echo back unchanged."
          },
          "completed_by_credential_name": {
            "type": "string",
            "description": "Server-stamped credential label. Echo back unchanged."
          },
          "updated_at": {
            "type": "string",
            "description": "Server-stamped. Echo back unchanged; ignored on new rows."
          },
          "updated_by": {
            "type": "string",
            "description": "Server-stamped user id. Echo back unchanged."
          },
          "updated_by_credential_name": {
            "type": "string",
            "description": "Server-stamped credential label. Echo back unchanged."
          }
        },
        "required": [
          "text"
        ]
      }
    },
    "constraints": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "non_goals": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "impacted_documents": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Array of {id, title}."
    },
    "linked_document_ids": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Document IDs to link. Titles resolved automatically."
    },
    "impacted_diagrams": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Array of {id, name}."
    },
    "impacted_components": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "agent_ready": {
      "type": "boolean"
    },
    "agent_missing_info": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "agent_recommended_action": {
      "type": "string"
    },
    "agent_complexity": {
      "type": "string",
      "description": "low, medium, high, very_high."
    },
    "agent_confidence": {
      "type": "number",
      "description": "0.00 to 1.00."
    },
    "agent_brief": {
      "type": "string"
    },
    "target_date": {
      "type": "string",
      "description": "YYYY-MM-DD."
    },
    "start_date": {
      "type": "string",
      "description": "YYYY-MM-DD."
    },
    "end_date": {
      "type": "string",
      "description": "YYYY-MM-DD."
    },
    "owner_id": {
      "type": "string",
      "description": "User UUID to assign as the owner. MUTUALLY EXCLUSIVE with owner_team_id — set one or the other, never both. Use listAssignablePrincipals(projectId, kind='user', q='…') to look up valid user UUIDs."
    },
    "owner_team_id": {
      "type": "string",
      "description": "Team UUID to assign as the owner (assigns the whole team rather than an individual). MUTUALLY EXCLUSIVE with owner_id. Use listTeams(workspaceId) or listAssignablePrincipals(projectId, kind='team') to look up valid team UUIDs."
    },
    "plan_id": {
      "type": "string",
      "description": "Link to a plan."
    },
    "phase_id": {
      "type": "string",
      "description": "Assign to a phase."
    },
    "is_task": {
      "type": "boolean",
      "description": "Mark as task. Default: false. Prefer setting type='task' instead — is_task is kept in sync from the type enum by a DB trigger, and rows with type='task' get the TAS- friendly_id prefix while all others get IMP-."
    },
    "description": {
      "type": "string"
    },
    "wbs_code": {
      "type": "string",
      "description": "Work breakdown structure code."
    },
    "percent_complete": {
      "type": "number",
      "description": "Progress percentage (0-100). Null means not tracked."
    },
    "source_channel": {
      "type": "string"
    },
    "impacted_repositories": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "relationships": {
      "type": "object",
      "description": "Free-form JSON for logical links: blocks, blocked_by, duplicates, supersedes, relates_to (arrays of item IDs)."
    },
    "metadata": {
      "type": "object",
      "description": "Free-form JSON stored alongside the item. On updateImprovement this MERGES rather than replaces."
    }
  },
  "required": [
    "projectId",
    "title"
  ]
}