skills/ce-doc-review/references/findings-schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Document Review Findings",
  "description": "Structured output schema for document review persona agents",
  "type": "object",
  "required": ["reviewer", "findings", "residual_risks", "deferred_questions"],
  "properties": {
    "reviewer": {
      "type": "string",
      "description": "Persona name that produced this output (e.g., 'coherence', 'feasibility', 'product-lens')"
    },
    "findings": {
      "type": "array",
      "description": "List of document review findings. Empty array if no issues found.",
      "items": {
        "type": "object",
        "required": [
          "title",
          "severity",
          "section",
          "why_it_matters",
          "finding_type",
          "autofix_class",
          "confidence",
          "evidence"
        ],
        "properties": {
          "title": {
            "type": "string",
            "description": "Short, specific issue title. 10 words or fewer.",
            "maxLength": 100
          },
          "severity": {
            "type": "string",
            "enum": ["P0", "P1", "P2", "P3"],
            "description": "Issue severity level"
          },
          "section": {
            "type": "string",
            "description": "Document section where the issue appears, named so a reader who does not have the document open can tell what it is. Give the identifier a short handle on first mention: 'U1 - Establish profile contracts', not 'U1'. Plain section names that need no handle are fine as-is (e.g., 'Requirements Trace', 'Overview')."
          },
          "why_it_matters": {
            "type": "string",
            "description": "Impact statement -- not 'what is wrong' but 'what goes wrong if not addressed'"
          },
          "autofix_class": {
            "type": "string",
            "enum": ["safe_auto", "gated_auto", "manual"],
            "description": "How to handle the finding. safe_auto = a mechanical correction with one right answer that follows directly from authoritative content. gated_auto = a concrete correction to document meaning for the agreed outcome. Synthesis applies it only with sufficient edit authority; otherwise it needs approval with the other proposed edits. Several workable technical approaches do not by themselves require a user decision. manual = an unresolved user choice or essential information investigation cannot obtain. Confidence and reviewer independence impose separate limits on what can apply."
          },
          "finding_type": {
            "type": "string",
            "enum": ["error", "omission"],
            "description": "Whether the admitted defect is incorrect or incompatible instructions (error), or a necessary decision or constraint not supplied by the document, its references, or existing conventions (omission). Missing repetition or optional detail is not an omission."
          },
          "suggested_fix": {
            "type": ["string", "null"],
            "description": "Concrete fix text. Omit or null if no good fix is obvious -- a bad suggestion is worse than none."
          },
          "confidence": {
            "type": "integer",
            "enum": [0, 25, 50, 75, 100],
            "description": "Anchored confidence score. Use exactly one of 0, 25, 50, 75, 100. Each anchor has a behavioral criterion the reviewer must honestly self-apply. 0: Not confident at all. This is a false positive that does not stand up to light scrutiny, or a pre-existing issue the document did not introduce. 25: Somewhat confident. Might be a real issue but could also be a false positive; the reviewer was not able to verify. 50: Moderately confident. The reviewer verified a useful advisory concern below the actionable bar and can state its concrete benefit. Preferences and nits without that benefit are suppressed, not routed to FYI. 75: Highly confident. The reviewer double-checked and verified the issue will be hit in practice by implementers or readers of this document. The existing approach is insufficient. The issue is important and will directly impact plan correctness, implementer understanding, or downstream execution. 100: Absolutely certain. The reviewer double-checked and confirmed the issue. The evidence directly confirms it will happen frequently in practice. The document text, codebase, or cross-references leave no room for interpretation."
          },
          "evidence": {
            "type": "array",
            "description": "Quoted text from the document that supports this finding. At least 1 item.",
            "items": { "type": "string" },
            "minItems": 1
          }
        }
      }
    },
    "residual_risks": {
      "type": "array",
      "description": "Distinct uncertainty with evidence of a material consequence for the agreed outcome. Apply the same admission standard as findings; omit rejected claims, preferences, and successful verifications.",
      "items": { "type": "string" }
    },
    "deferred_questions": {
      "type": "array",
      "description": "Essential information or decisions a later stage must resolve to deliver the agreed outcome. Omit questions already answered by the contract or discoverable project evidence.",
      "items": { "type": "string" }
    }
  }
}