86 lines
4.9 KiB
JSON
86 lines
4.9 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": ["safe_auto", "gated_auto", "manual"],
|
|
"description": "How this issue should be handled. safe_auto = one clear correct fix applied silently (typo, wrong count, stale cross-reference, mechanically-implied addition, terminology drift). gated_auto = concrete fix exists but touches document meaning or scope and warrants user confirmation (substantive additions from codebase-pattern-resolved fixes, framework-native-API substitutions, missing standard controls). manual = requires user judgment; multiple valid approaches. Low-confidence manual findings surface in an FYI subsection at the presentation layer."
|
|
},
|
|
"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": "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 this is a real issue but it may be a nitpick or not meaningfully affect plan correctness. Relative to the rest of the document, it is not very important. Advisory observations (the honest answer to 'what breaks if we do not fix this?' is 'nothing breaks, but...') land here. 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": "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" }
|
|
}
|
|
}
|
|
}
|