go-go-golems/devctl/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.

1. 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.

1. Build a JSON report model following the report contract.
2. Validate the JSON model before rendering. The wrapper resolves its own directory, so it works from any current working directory:

scripts/validate.sh report.json

1. Render it with the bundled script:

python3 scripts/render_report.py --input report.json --output session-context-audit.html

1. If visual inspection is requested, open the standalone file directly by default:

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.

1. 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
• 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