Session Insights Report

Contract

Generate user insights in four stages:

1. Evidence extraction: build bounded evidence from JSONL, audit logs, config, skills, hooks, permissions, validations, and bounded transcript metadata.
2. Insight pack: convert facets into compact cards and signals such as source coverage, validation behavior, repeated friction, observed hooks, tool mix, hook-command/script attribution, longSessions, action candidates, and coverage gaps.
3. Analysis and review: write the insights report from the insight pack, then review that report against the same bounded evidence for overclaims, missing scope, and cross-tool leakage.
4. Revision and quality gate: apply the review, then verify the report meets the quality bar below before presenting it as final.

Do not call a metrics report or static inspection output a user insights report. The report must explain how the user's workflow should change.

Default to one final report per tool. Do not merge Qoder, Codex, and Claude Code into one report unless the user explicitly requests a comparison or synthesis. For explicit long-session, token/credit, model-choice, or usage-efficiency questions, load Session Usage Efficiency and run the full deterministic census before any semantic candidate review.

Evidence Handoff

Complete source discovery and bounded evidence collection through Sessions Diagnostics. This reference starts from its scoped facets and insights outputs; it does not own or repeat the analyzer command ladder. Neither output is the final user report. If the source probe fails, returns no enabled roots, or the insight pack is sampled, report that scope and downgrade confidence instead of filling gaps from global assumptions.

When hook events are prominent, prefer facets.topHookCommands or insights.keySignals.topHookCommands over topHooks alone. These values name the observed hook event plus sanitized command/script target, not full raw commands. If a high-frequency hook has no command attribution, say so and open a bounded event sample only when that detail affects the recommendation. Static hook config or asset inventory can provide configured candidates, but not observed command attribution.

Use exact confidence labels Low, Medium, or High. Sampled session facets default to Low or Medium confidence unless proven representative. Do not write Moderate. Use High only when the run inspected the full intended session set or the sampling boundary is explicitly representative for the claim. Do not render sourceCoverage counts as percentages unless the analyzer explicitly returns a percentage field. Use insights.keySignals.longSessions for session complexity claims. Active long sessions and wall-span long sessions are separate signals: active-long duration produces an outcome-review candidate, while wall-span-only sessions are idle/resume evidence. Neither duration signal by itself recommends subagents, Custom Agents, Experts, tooling changes, or a different model.

Long Session Review Heuristic

Use this sequence before deciding whether any improvement is needed:

1. Compare longSessions.longActiveCount, longWallCount, wallOnlyCount, and longActiveRatio. Treat active estimates as work evidence; treat wall-span-only rows as idle/resume evidence.
2. Inspect representative active-long rows only enough to review task family, outcome, and friction; keep raw ids and excerpts private.
3. Treat unreviewed rows as investigation leads, not findings. If review shows a normal successful long task, close the lead without an improvement.
4. Recommend subagents or Experts only when reviewed active-long sessions repeat and the work has separable roles such as research, implementation, verification, specialist review, or risk analysis.
5. Use Loop Discovery before suggesting a durable Custom Agent, Skill-backed review loop, or other owner.

Report Quality Bar

A good user insights report must:

• Lead with the behavior change the user should make.
• Cover exactly one selected tool unless the user explicitly asked for a mixed comparison.
• Use insight cards, not a metric dump.
• Tie every insight to evidence and confidence.
• Name metric scope explicitly: workspace-only, platform-wide, all-workspace, or global. Every final insight card must include Scope.
• Keep candidate findings as candidate/likely unless file content was manually inspected.
• Mark inferred mechanisms as likely. For example, high sed counts plus zero tracked edits can imply bash-based editing, but the exact flag or command shape still needs trace evidence.
• For a single-tool report, describe that tool's usage and quality without ranking it against other tools.
• For an explicit mixed report, distinguish platform role from platform quality. For example, Codex may be used for implementation while Qoder may be used for plugin/runtime checks.
• Separate installed skill files, loaded/activated skill signals, and Skill tool-call counts. Loaded skill prompts prove context injection, not tool invocation.
• Separate configured hooks from observed hook enforcement.
• For important observed hook counters, name the hook command/script target when the analyzer provides it; otherwise mark command/script attribution as unavailable instead of guessing from static config.
• Separate validation command existence from validation-after-edit behavior. Use insights.keySignals.validationAfterEdit to decide whether the bounded sample shows edit events followed by validation commands, edit events without later validation, validation without edits, or no observed edits.
• For long-session reports, name the active-vs-wall boundary. Recommend subagents or Experts only from repeated active long-session evidence, and route durable role creation through Loop Discovery before suggesting a Custom Agent or Skill.
• For Qoder Read failures, separate path/tooling failures from model-quality claims. Recommend a stronger model only when model attribution has comparable per-model Read samples; otherwise recommend a controlled model A/B test and Read failure path logging.
• For usage reports, prefer workspace-scoped evidence. Treat global audit coverage as context only, not as proof of current workspace behavior.
• Treat user feedback in the conversation as first-class evidence when it is included as a bounded artifact.
• Keep static-only and sampled evidence explicit.