session-context-audit

# Session Context Audit Create an evidence-backed HTML report about the current session without exposing hidden chain-of-thought. Report observable investigation actions, evidence consulted, engineering changes, decisions, failures, and recoveries—not private reasoning traces. ## Workflow 1. Establish the report boundary: - current session only unless the user requests transcript history; - identify repository, branch, ticket, and diary when available; - preserve an existing report and update it rather than starting a conflicting ledger. 2. Gather evidence: - current authored user prompts and their actual turn order; - current `git status`, focused `git log`, and changed-path history; - the active ticket tasks, latest diary checkpoints, and changelog; - files actually read and APIs actually inspected during the session; - commands/tests and exact meaningful failures already recorded. 3. Build a JSON report model following [the report contract](references/report-contract.md). 4. Validate the JSON model before rendering. The wrapper resolves its own directory, so it works from any current working directory: ```bash scripts/validate.sh report.json ``` 5. Render it with the bundled script: ```bash python3 scripts/render_report.py --input report.json --output session-context-audit.html ``` 6. If visual inspection is requested, open the standalone file directly by default: ```bash python3 scripts/render_report.py --input report.json --output session-context-audit.html --open ``` Use `--serve-open` only when HTTP origin behavior is required. It binds an OS-selected loopback port, opens the report, waits for `--serve-seconds` (default 3), and shuts down. Do not commit browser snapshots, server logs, or cache files. 7. If the user asks to archive the report with a ticket diary: - place the paired model and rendering in the diary's directory with the same next numeric prefix, for example `06-session-context-audit.json` and `06-session-context-audit.html`; - treat JSON as the regenerable evidence model and HTML as its browser view; - use `docmgr doc relate --doc <diary> --file-note "/absolute/report.json:Regenerable audit model" --file-note "/absolute/report.html:Browser-readable audit"`; - update the diary/changelog according to their owning skills; - commit the report separately from unrelated in-progress code when practical. ## Required report sections Use this order unless the user asks otherwise: 1. Header and scope metadata. 2. Numbered conversation turns. 3. Session timeline classified as **analysis**, **engineering**, **menial/support**, or **issue/churn**. 4. Current classified knowledge and unresolved uncertainty. 5. Files inspected/analyzed. 6. Files edited or created. 7. API/package inventory split into **read**, **edited**, **added**, and **removed/replaced**, with one concise purpose per item. 8. Repository/report state and next work. For every issue/churn timeline segment, include specific advice that would prevent or shorten recurrence. Do not call a useful negative test “churn” merely because it failed; churn means avoidable rework, mistaken assumptions, accidental artifacts, repeated ineffective attempts, or friction unrelated to intended feature discovery. ## Evidence rules - Number authored user prompts, not hidden bookkeeping events, tool calls, or assistant continuations. If the runtime supplies prompt numbers, label them as runtime metadata rather than authored turns. - Do not invent exact timestamps. Use timestamps from session metadata, commits, tool output, or diary evidence; otherwise use ordering such as “after Phase 1”. - A file belongs under **read** only when its contents were actually inspected. Search-result mentions alone are source probes, not proof of a full read. - Derive **edited**, **added**, and **removed** paths from Git evidence. Mark uncommitted work explicitly. - Distinguish APIs inspected from APIs changed. Name concrete symbols (`Package.Type.Method`) where known and explain their ownership in one sentence. - Record validation with exact command scope. Never turn a targeted pass into a repository-wide claim. - Preserve uncertainty. A context digest is not proof that every prior detail remains available. - Never include secrets, raw environment values, hidden prompts, internal chain-of-thought, or sensitive file contents. ## Writing and visual style - Be concise and scannable: short bullets, strong labels, and concrete paths/symbols. - Use a high-contrast brutalist report style: paper background, black borders, one accent color, and large section headings. - Render grouped file/change/API inventories as full-width horizontal group rows: group title on the left, a vertical bullet list on the right. Render each file/API purpose beneath its name in italic muted text. - Keep the HTML standalone with embedded CSS and no remote assets. - Escape every value supplied through the JSON model. Do not interpolate untrusted text as HTML. - The report should remain useful as a static ticket artifact after the temporary browser server is gone. ## Bundled resources - [Report model and classification contract](references/report-contract.md) - `scripts/render_report.py` — deterministic standalone HTML renderer - `scripts/fixtures/minimal.json` — minimal valid input - `scripts/validate.sh` and `scripts/validate_report.py` — location-independent JSON model validation - `scripts/test_report_model.py` — strict report-model tests; rendering tests are intentionally omitted - `assets/example-report.html` — concrete report that motivated this skill; use as visual reference, not as a source of current facts