Write and Review Security Docs for Developers

## Write Advice Developers Can Apply, Staying on Security Write for developers rather than security specialists. Guidance must be accurate, practical, concise, and opinionated. Prefer good advice that a developer can apply over theoretically best advice that is too complex to follow. Keep every recommendation within the document's security threat model. General code quality, performance, and architecture advice belongs elsewhere unless it directly controls a security risk. Treat contribution rules as mandatory for every authoring tool. Preserve the repository's authoritative human process and writing guides, and use the shorter agent guide only as an operational summary. ## Read Every Cited Source and Check It Supports the Claim Fetch and read every cited source, then confirm that it supports the exact claim. Never invent or guess a URL, cite a page that redirects to an unrelated landing page, or rely on training memory or a summary. Link the specific page or section that contains the supporting evidence. Verify internal cross-links before using them. Do not point to a document or anchor that does not exist. When citation-density gates apply, include at least one inline HTTPS citation in every new H2 section. Give separate support to novel, surprising, parameter-specific, or contestable claims; established common practice does not need a citation on every sentence. Sources may be inline or collected in a References section. Prefer standards, government or industry security guidance, official project and vendor documentation, well-maintained platform references, canonical source repositories, and peer-reviewed research. Avoid search-optimized marketing farms. Citation gates are a floor, not proof that the content is correct. ## Match Each Threat with a Fix and Say What It Does Not Stop Citations are necessary but not sufficient. Pair every threat with a concrete countermeasure and state explicitly what the control does and does not protect against. Do not introduce attacks outside the stated threat model without a clear caveat. A control for one layer must not be presented as protection against compromise at another layer. Add only guidance that is genuinely a security control or risk. Review correctness, developer practicality, and topic relevance independently; a well-cited but incorrect recommendation must still be rejected. ## Keep Each Change Small and Link Instead of Copying Limit one change to a single guidance document or a small, clearly coordinated set. Without an approved tracking issue, do not exceed three content documents or 1,500 net added lines when those are the repository's stated limits. Keep dependency, automation, and typo-only changes under their own scope rules. Start from a clean branch based on the default branch and keep one topic per branch. Never open two change requests from the same branch because unrelated changes can leak between them. Require an approved issue before proposing a new or substantially rewritten guidance document. Do not bundle drive-by formatting, mass edits, or unrelated fixes. Search the current document, related documents, and the repository index before adding a section. Link to existing guidance instead of reproducing it. Preserve intentional hub-and-spoke document families. Coordinated cross-links are valid; copying another document's guidance is not. If content belongs to a different topic, move it to the appropriate existing or new document rather than stretching the current scope. ## Explain the Design First and Use Code Only When the Topic Needs It For general topics, favor architectural patterns, design principles, and security decisions over language-specific code. Code ages quickly, and isolated snippets can be insecure when copied without their original context. Use code freely when the topic is inherently language-specific, injection-focused, parameterization-focused, or about concrete hardening. Code density is appropriate when executable detail is the security guidance rather than incidental boilerplate. Keep illustrative code short, label fenced blocks with a language when practical, and do not present examples as production-ready unless they have been designed and reviewed to that standard. ## Cut Filler and Recommend One Clear Approach Cut generic preambles, repeated background, exhaustive option lists, and fashionable but empty introductions. Recommend a specific approach and explain only the context a developer needs to apply it safely. Use US English, run spelling and terminology checks, and keep sentences accessible to non-native readers. Define non-obvious acronyms on first use, while leaving universally familiar protocol and locator abbreviations unexplained when the style guide permits. Rewrite or remove passages that sound like generic automated prose. Concision must not erase constraints, exceptions, threat boundaries, or the reason a recommendation is safer. ## Follow the Repository's Markdown and Image Rules Use Markdown and avoid raw HTML except for explicitly permitted elements such as `details` and `summary`. Use hyphen bullets, Markdown bold, and block quotes consistently. Leave a blank line after every heading. A typical document begins with one H1 and an Introduction, continues with focused H2 sections, and may end with References. Three to six H2 sections is a useful default, not a hard maximum. Do not add a manual table of contents when publication tooling generates it. Follow the repository's filename contract. Use only letters, numbers, hyphens, and underscores, and retain any required suffix such as `_Cheat_Sheet.md`. Start new documents from the approved template. Store assets in the designated asset directory. Use the approved image format, provide meaningful alternative text, and reference assets with the correct relative path. Write links inline with descriptive labels and use HTTPS whenever possible. ## Run Lint and Link Checks Before Asking for Review Run the repository-defined Markdown lint, terminology check, and link checker before proposing changes. Also run scope, citation-density, and other policy gates that apply to the modified content. Treat a failed local or continuous-integration check as a defect to investigate, not a reason to bypass the gate. Review the final difference so generated or automated changes do not hide unrelated edits. Understand the limit of automation. Mechanical checks can detect malformed Markdown, disallowed terminology, dead links, excessive scope, and missing citation patterns, but they cannot determine whether a source supports a claim, advice is correct, the topic belongs in the document, or content duplicates existing guidance. ## Disclose AI Help and Review from Several Angles Disclose material AI assistance in the change-request description. Record the tool name, known version, and prompt in the repository's designated disclosure section. This requirement applies to every AI tool; omission may invalidate the contribution. Review security guidance across separate dimensions: security correctness, developer practicality, source and link quality, duplication and placement, and language quality. Specialized reviewers may work independently, but their findings should be consolidated into one evidence-based verdict. Use explicit outcomes such as accept, request changes, or close. Cite concrete evidence for blocking findings, distinguish mechanical failures from judgment failures, and do not approve merely because citations or automated checks exist.