gdocs-audit-report

name	gdocs-audit-report
description	Expert skill for creating, formatting, and maintaining security audit reports in Google Docs via the Docs API. Use when asked to write, update, style, or fix an audit report document - including finding formatting, summary tables, inline code styling, bullet conversion, cross-reference hyperlinks, and severity color schemes. Covers auth, index-drift safety, and all common formatting pitfalls.

Google Docs Security Audit Report

Overview

This skill provides patterns, constants, and gotcha-avoidance for building and maintaining security audit reports in Google Docs using the Docs API (service account auth). It encodes hard-won lessons around index drift, code styling multi-pass, paragraph vs text backgrounds, heading anchor URLs, and cross-reference linking.

Always read references/api-patterns.md and references/formatting-standards.md before writing any script.

Workflow

1. Auth          → make_token() from scripts/gdocs_auth.py
2. get_doc()     → fresh snapshot before EVERY batch of edits
3. Build ops     → sort ALL ops highest-index-first
4. do_batch()    → send in chunks of ≤50
5. Verify        → get_doc() again and spot-check changed ranges

Critical Gotchas (read these first)

1. Index drift

Any insert/delete shifts every index above it. Always sort ops high→low. Always get_doc() fresh.

2. Text bg ≠ paragraph bg

updateTextStyle.backgroundColor only covers character width - leaves white gaps between lines in code blocks. Use updateParagraphStyle.shading.backgroundColor + spaceAbove/Below: 0 for full-width code block backgrounds.

3. headingId already has h. prefix

Anchor URL = #heading={headingId} - not #heading=h.{headingId}.

4. Code styling needs multiple passes

After updateTextStyle splits a run, new unstyled sub-runs appear. Always do a second full-doc re-scan after the first styling pass.

5. Sort code terms longest-first

Prevents maxRelayFeeBPS matching before assetConfig.maxRelayFeeBPS and leaving a partial un-styled prefix.

6. Backtick removal order (per segment, high→low)

Delete closing backtick → style inner → delete opening backtick - all in one batch.

7. Bullet conversion

createParagraphBullets does not change indices. Then deleteContentRange the - prefix high→low in a second batch.

8. Cross-reference links: skip only already-linked runs

Scan ALL runs for X-NN regex - only skip runs where textStyle.link is already set. Do NOT also filter by font (Courier runs can contain xrefs too).

9. Table cell content replace

Delete to elements[-1].endIndex - 1 (keep the required trailing \n), then insert. Sort delete (higher) before insert (lower) in same batch.

10. replaceAllText for bulk renames

Use replaceAllText for ID renames (e.g. renumbering findings). Same-length replacements are index-safe. Do in one batch, longest/most-specific strings first.

Formatting Standards

See references/formatting-standards.md for:

• Severity RGB colors (Critical, High, Medium, Low, Unmitigated)
• Heading purple, code purple, code bg gray
• Finding structure template
• Summary table column definitions
• Finding ID scheme (C-01, H-01, etc.)

API Patterns

See references/api-patterns.md for:

• Auth boilerplate
• All common op templates (style, delete, insert, hyperlink, bullets, paragraph shading)
• Heading anchor URL construction
• Cross-reference linking pattern
• Inline code multi-pass approach

Resources

• scripts/gdocs_auth.py - reusable auth + get_doc + do_batch helpers
• references/api-patterns.md - op templates and patterns
• references/formatting-standards.md - colors, typography, structure constants
• references/how-to-create-google-service-account.md - one-time setup: instruct the user to create a service account, advise the user to restrict it to the AI-only Drive folder/file (via google share feature), and provide the JSON key path