111 lines
5.6 KiB
JSON
111 lines
5.6 KiB
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 (e.g., 'Requirements Trace', 'Implementation Unit 3', '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": ["auto", "batch_confirm", "present"],
|
|
"description": "How this issue should be handled. auto = local deterministic fix applied silently (terminology, formatting, cross-references, completeness corrections). batch_confirm = obvious fix with a clear correct answer, but touches meaning enough to warrant grouped approval. present = requires individual user judgment."
|
|
},
|
|
"finding_type": {
|
|
"type": "string",
|
|
"enum": ["error", "omission"],
|
|
"description": "Whether the finding is a mistake in what the document says (error) or something the document forgot to say (omission). Errors are design tensions, contradictions, or incorrect statements. Omissions are missing mechanical steps, forgotten list entries, or absent details."
|
|
},
|
|
"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": "number",
|
|
"description": "Reviewer confidence in this finding, calibrated per persona",
|
|
"minimum": 0.0,
|
|
"maximum": 1.0
|
|
},
|
|
"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": "Risks the reviewer noticed but could not confirm as findings (below confidence threshold)",
|
|
"items": { "type": "string" }
|
|
},
|
|
"deferred_questions": {
|
|
"type": "array",
|
|
"description": "Questions that should be resolved in a later workflow stage (planning, implementation)",
|
|
"items": { "type": "string" }
|
|
}
|
|
},
|
|
|
|
"_meta": {
|
|
"confidence_thresholds": {
|
|
"suppress": "Below 0.50 -- do not report. Finding is speculative noise.",
|
|
"flag": "0.50-0.69 -- include only when the persona's calibration says the issue is actionable at that confidence.",
|
|
"report": "0.70+ -- report with full confidence."
|
|
},
|
|
"severity_definitions": {
|
|
"P0": "Contradictions or gaps that would cause building the wrong thing. Must fix before proceeding.",
|
|
"P1": "Significant gap likely hit during planning or implementation. Should fix.",
|
|
"P2": "Moderate issue with meaningful downside. Fix if straightforward.",
|
|
"P3": "Minor improvement. User's discretion."
|
|
},
|
|
"autofix_classes": {
|
|
"_principle": "Autofix class is independent of severity. A P1 finding can be auto if the fix is deterministic. The test: can the correct fix be derived from the document's own content without judgment?",
|
|
"auto": "Fix is derivable from the document itself -- one part is clearly authoritative over another, reconcile toward the authority. Includes: summary/detail mismatches, wrong counts, missing list entries, stale cross-references, terminology drift, prose/diagram contradictions where prose is authoritative. Must include suggested_fix.",
|
|
"batch_confirm": "One clear correct answer, but authors new content where exact wording needs verification. Grouped for single approval. Examples: adding a missing step mechanically implied by other content, defining an implied-but-unstated threshold. Must include suggested_fix.",
|
|
"present": "Requires individual user judgment -- strategic questions, design tradeoffs, or findings where reasonable people could disagree on the right action."
|
|
},
|
|
"finding_types": {
|
|
"error": "Something the document says that is wrong -- contradictions, incorrect statements, design tensions, incoherent tradeoffs. These are mistakes in what exists.",
|
|
"omission": "Something the document forgot to say -- missing mechanical steps, absent list entries, undefined thresholds, forgotten cross-references. These are gaps in completeness."
|
|
}
|
|
}
|
|
}
|