Auth Documentation Completeness Audit Prompt

This prompt is designed for technical writing teams, security engineers, and API product managers who need to systematically audit an existing set of authentication and authorization documentation. The core job-to-be-done is to move from a subjective feeling that 'the docs might be incomplete' to a structured, prioritized audit report that flags specific gaps—such as missing grant types, undocumented error codes, stale code samples, or contradictory instructions across pages. The ideal user is someone responsible for documentation quality who needs an automated first pass before a manual deep-dive, not a replacement for human security review.

Use this prompt when you have a collection of auth documentation pages (OAuth flows, API key guides, session management, scope references) and you need a completeness audit against a known standard like an RFC, an OpenAPI spec, or an internal auth policy. The prompt requires you to provide the documentation content as [DOCUMENTATION_PAGES], a reference specification as [AUTH_STANDARD], and an optional [AUDIT_CRITERIA] list to focus the audit on specific dimensions such as error handling, code sample freshness, or terminology consistency. The output is a structured report with severity classifications (Critical, High, Medium, Low) and fix prioritization, making it directly usable as a sprint planning input.

Do not use this prompt for real-time auth debugging, live traffic analysis, or as a substitute for a penetration test. It audits documentation, not running systems. Avoid using it on a single page in isolation—the value comes from cross-page consistency checks and gap analysis against a reference standard. If your documentation is auto-generated from an OpenAPI spec, this prompt is better suited for auditing the surrounding conceptual guides, quickstarts, and troubleshooting pages rather than the reference itself. For high-risk auth flows involving financial transactions or health data, always follow the automated audit with a manual security review and consider pairing this prompt with the OAuth 2.0 Error Response Reference Generation Prompt to fill any error catalog gaps identified.

This prompt template is the core of the Auth Documentation Completeness Audit. It is designed to be copied directly into your AI harness, with square-bracket placeholders that you replace with your specific documentation content, evaluation criteria, and output requirements. The template instructs the model to act as a thorough technical reviewer, systematically checking for missing grant types, undocumented error codes, stale code samples, and contradictory instructions across pages. It produces a structured audit report with severity classification and fix prioritization, making it actionable for technical writing teams.

textCopy
You are an expert technical documentation auditor specializing in authentication and authorization systems. Your task is to perform a completeness audit on the provided auth documentation.

## INPUT DOCUMENTATION
[INPUT]

## AUDIT CRITERIA
Review the documentation against the following completeness dimensions:
- **Grant Types and Flows**: Are all applicable OAuth 2.0 grant types, API key schemes, session-based auth, and token exchange patterns fully documented? Flag any missing flows.
- **Error Codes and Responses**: Are all possible error responses documented with HTTP status codes, error body schemas, and resolution steps? Check against the OAuth 2.0 RFC error registry and common implementation errors.
- **Code Samples**: Are all code samples syntactically correct, using current library versions, and free of security anti-patterns (hardcoded secrets, localStorage for tokens, missing PKCE)?
- **Cross-Page Consistency**: Do parameter names, endpoint URLs, scope strings, and token lifetime values match across all pages? Flag any contradictions.
- **Security Considerations**: Are token storage best practices, CSRF protection, PKCE requirements, rate limiting, and secret rotation documented?
- **Scope Definitions**: Is every scope defined with its exact permissions and the endpoints it unlocks? Check for undocumented scopes or over-scoped examples.
- **Token Lifecycle**: Are token creation, refresh, expiration, revocation, and rotation fully documented with exact lifetimes and renewal procedures?

## OUTPUT FORMAT
Produce a structured JSON audit report with the following schema:
[OUTPUT_SCHEMA]

## CONSTRAINTS
[CONSTRAINTS]

## EXAMPLES
Here are examples of findings at different severity levels:
[EXAMPLES]

## RISK LEVEL
[RISK_LEVEL]

For each finding, include:
1. **Severity**: critical, high, medium, or low
2. **Category**: grant_type, error_code, code_sample, consistency, security, scope, token_lifecycle, or other
3. **Location**: specific page, section, or code block reference
4. **Description**: what is missing, incorrect, or contradictory
5. **Impact**: what breaks or what security risk exists if this is not fixed
6. **Fix Recommendation**: specific, actionable guidance for the writer
7. **Priority Score**: 1-10 based on user impact and security risk

Group findings by severity and sort by priority score within each group. Include a summary section with counts by severity and category.

To adapt this template, replace the square-bracket placeholders with your specific content and requirements. [INPUT] should contain the full text of your auth documentation, ideally concatenated from multiple pages with clear section markers. [OUTPUT_SCHEMA] should specify the exact JSON structure you want, including field names, types, and whether fields are required. [CONSTRAINTS] can include page limits, specific OAuth flows to focus on, or style guide rules to enforce. [EXAMPLES] should provide 2-3 example findings at different severity levels to calibrate the model's judgment. [RISK_LEVEL] should indicate the deployment context (e.g., production auth system, pre-launch review, compliance audit) to help the model calibrate severity appropriately. After copying the template, test it against a known-good documentation set to verify the output structure matches your expectations before running it on real docs.

This prompt is designed to be run as a batch job against a set of documentation pages, not as a real-time chat interaction. The primary integration point is a script or CI/CD pipeline that iterates over a list of URLs or file paths, sends each document's content as the [DOCUMENTATION_CONTENT] input, and collects the structured audit reports. Because the output is a JSON object with a severity classification, the harness should parse each response and aggregate findings into a dashboard or issue tracker. The model choice matters: use a model with strong instruction-following and structured output capabilities (e.g., GPT-4o, Claude 3.5 Sonnet) and set temperature to 0 to maximize consistency across pages.

The implementation harness must enforce the output schema before accepting a result. Wrap the model call in a validation layer that checks for the required top-level keys (document_title, audit_date, findings, overall_score), verifies that each finding has a valid severity enum value (critical, high, medium, low), and confirms that overall_score is an integer between 0 and 100. If validation fails, implement a single retry with the validation error message appended to the prompt as additional [CONSTRAINTS]. Log every validation failure and retry attempt for observability. For high-stakes documentation (e.g., OAuth grant types, token storage guidance), route findings with critical or high severity to a human review queue before they are published to the engineering team.

To scale this across a large doc set, build a simple orchestrator that reads a manifest of document paths, sends each through the prompt, and writes the validated JSON output to a structured store (e.g., a database or a directory of JSON files). Use the overall_score field to sort pages by risk, and generate a summary report that lists every critical finding across all documents. Avoid running this prompt on pages that are not authentication-related, as the evaluation criteria are tuned for grant types, error codes, token flows, and scope definitions. For ongoing use, integrate the harness into your documentation CI pipeline so that every PR touching auth docs triggers a completeness audit on the changed files, blocking merges if new critical findings are introduced.