Define the reader’s decision before the headline
Ask what the document must help someone decide. An engineer may need to reproduce an authorization failure; an incident lead may need to choose a containment action; a customer may need to understand a product limitation. Those are different documents. Write the intended reader and decision at the top of the internal brief. Assign a technical reviewer with access to the relevant system or original evidence rather than choosing a reviewer only because they edit well.
Create a claim ledger before drafting the narrative. Give each material claim a source, a date, an owner and an evidence location. Mark whether it is directly observed, reported by another party, inferred from observations or still unresolved. For example, a successful test using an administrative token establishes what that token could do in the tested environment. It does not establish that an unauthenticated attacker could obtain the same result.
Make the technical path reproducible
For a finding, record the affected version or revision, starting permissions, relevant configuration and the smallest sequence that demonstrates the consequence. Keep the input and the observed result together. Where a live reproduction would alter real data or assets, describe a controlled environment and the limitations of the demonstration. A screenshot of an error message is useful context, but the reader also needs the preconditions that produced it.
Explain why the result matters in the language of the system: an unauthorized account can read a different tenant’s record, an operation bypasses an approval rule, or a transaction violates a stated accounting invariant. List the assumptions that limit that conclusion. Recommend a change to the responsible boundary, then state how a reviewer could distinguish a corrected implementation from the original behavior. Avoid replacing this reasoning with a severity label.
Keep incident timelines and uncertainty inspectable
Choose and label a time zone for the timeline. Distinguish the time an event occurred, the time it was recorded and the time the team learned about it. Tie important entries to preserved logs, artifacts or an attributed public report. CISA’s incident playbook is useful background for the collection and coordination work; an article built from public reports should not imply access to evidence the author has not actually examined.
Ask the reviewer to identify one plausible alternative explanation for each consequential inference. What evidence would separate the alternatives? If the evidence is missing, preserve that uncertainty in the published wording. Attribute disputed accounts separately and avoid smoothing them into a single confident story. Do not treat a vendor’s statement, a third-party investigation and your own recommendation as interchangeable sources of certainty.
Review the release and plan the correction
Use two review passes. The first reviewer checks the mechanism, preconditions, scope and evidence. The second reads for clarity, accidental disclosure and mismatch between the headline and the supported conclusion. Google’s code-review guidance offers a useful general discipline: review changes for their substance, design and comprehensibility rather than concentrating only on surface style. Here, require a reviewer to trace a headline claim back to the ledger without help from the author.
Before release, remove credentials, personal information and unnecessary exploit detail, and confirm what the owner has authorized for publication. Preserve a private evidence record with appropriate access controls; do not publish sensitive artifacts simply to make the article look well supported. For a material correction, retain the original publication date, state what changed and when, and update related summaries. Test the process by asking a colleague to challenge a claim and following the correction path through to the public page.
Controls to take away
- Make the strength of the wording match the strength of the evidence.
- A reproduction is incomplete without its starting permissions and configuration.
- A correction process is part of publishing technical work.
Take this to your next review
Working checklist
Use this as a starting point, then assign owners and record evidence in your team's own system. Checks here reset when you leave or reload this note.
0 of 6 reviewed
Sources & further reading
The references below support this note. Adapt the procedures to your systems, access model and recovery requirements.
A correction or a better primary source? Send Raiders the article URL and evidence. Editorial policy.