poam-authoring

POA&M Authoring

Purpose

Turn the open weaknesses an assessment surfaced into a valid OSCAL Plan of Action and Milestones (plan-of-action-and-milestones.json) — each weakness tracked with a remediation plan, milestones, owner (POC), and due date.

This is the last step of the lifecycle: catalog → component-definition → assessment → **POA&M**.

Two halves of the job (read this first)

A POA&M is assessment-seeded but authored with the user — it is NOT a pure auto-conversion:

• Drafted automatically from the assessment (the what's wrong): POAM ID, weakness name & description, affected control ID(s), evidence.
• Elicited from the user (the plan — not in the assessment): remediation plan, milestones, point of contact, scheduled completion date, risk rating.

Draft the first half, then ask the user for the second half. Do not invent remediation plans.

Inputs (four paths)

• A) Assessment result → POA&M (default). An assessment skill markdown table, or an OSCAL assessment-results.json. Only its failed / non-compliant findings become POA&M items. If no assessment result is available, take a list of weaknesses directly from the user.
• B) FedRAMP POA&M .xlsx → POA&M. The user already has a FedRAMP-format POA&M spreadsheet (Open POA&M Items sheet; required columns POAM ID, Weakness Name, Weakness Description, Controls). Convert it with the trestle xlsx-to-oscal-poam task — see xlsx-to-oscal-poam.md. This path is control-centric (Controls required by the FedRAMP template) and less common; most users take path A.
• C) Component-definition → pre-defined POA&M (+ optional assessment linking). A component-definition.json (from the component-definition skill) declares, per component, the rules/checks mapped to controls. Because each check is a testable assertion, the full weakness catalog is known before assessment: pre-define one poam-item per rule/check with remediation authored up front, filling local-definitions from the component-definition (from-component-definition.md). Then, at assessment time, reference those pre-existing items — layer the assessment results in as observations/findings linked to the matching item, creating no new items (link-assessment.md). This closes the loop component-definition → POA&M → assessment. Path A is reactive (findings → items); path C is pre-defined (items → then assessed).
• D) Scan-tool remediation data → POA&M (reference-driven). A scanner/security tool emits its own remediation data (fix + severity + assets + owners/dates per weakness), to be held as a POA&M (often for another platform). You learn the tool's format and the desired output shape from a sample/reference the user provides, then map each record onto a pass-through risk (remediation in risk.remediations[], tool-specific fields as free-form props) — no per-tool code (from-scan-remediations.md). Path D is path A with the remediation/props filled from a customer reference rather than fixed fields.