Contribute Agent Logs

Add your agent conversation data to the team's insight scan. This skill discovers logs on your machine, analyzes them for patterns, saves a per-developer report, and re-runs synthesis to update the shared findings and HTML report.

Prerequisites

• An existing .tessl-insights-poc/ directory in the repo (someone must have run run-insight-scan first, or at minimum created the directory structure)
• Agent conversation logs on your machine (from Cursor, Claude Code, or other tools)

Optional Inputs

• logs-path (optional): Absolute path to a directory containing .jsonl agent logs. When provided, the skill skips the standard discovery locations (~/.cursor/projects/, ~/.claude/projects/) and analyzes logs from this path instead. Useful when logs live outside the default locations (e.g. pre-processed exports or custom collection directories).
  • Username inference from logs-path only kicks in when the path matches the known by-repo layout .../by-repo/<agent>/<repo>/<user>. For arbitrary export directories (e.g. /tmp/exports/2026-04-21) the skill falls back to the git config / whoami chain — pass username= if you need to override.
• username (optional): Explicitly set the contributing username. Takes precedence over both logs-path inference and the git config / whoami fallback. Required if logs-path points at an arbitrary directory that doesn't match the by-repo layout and you want a specific contributor name.

Invoke with the argument like logs-path=/path/to/logs. If omitted, the skill falls back to the standard discovery described in log-discovery.md.

Step 1: Verify Scan Directory Exists

if [ ! -d ".tessl-insights-poc/reports" ]; then
  echo "No .tessl-insights-poc/reports directory found."
  echo "Run the 'run-insight-scan' skill first to initialize the scan."
  exit 1
fi
mkdir -p ".tessl-insights-poc/reports/agent-logs"

Step 2: Resolve Username

Determine who is contributing. Resolution order:

1. If the username argument was provided, use it directly.
2. Otherwise, if logs-path matches the known by-repo layout (.../by-repo/<agent>/<repo>/<user>), use its final segment as the username.
3. Otherwise, fall back to git config → whoami → unknown-user. Ask the user to pass username= if the logs-path points at an arbitrary export directory and a specific contributor is intended.

# Start from explicit input, then path-derived (only for known by-repo layout), then fall back.
USERNAME="${USERNAME_INPUT:-}"
if [ -z "$USERNAME" ] && [ -n "$LOGS_PATH" ] \
  && printf '%s' "$LOGS_PATH" | grep -Eq '/by-repo/[^/]+/[^/]+/[^/]+/?$'; then
  USERNAME=$(basename "$LOGS_PATH" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9._-]//g')
fi
if [ -z "$USERNAME" ]; then
  USERNAME=$(git config user.name 2>/dev/null \
    | tr '[:upper:]' '[:lower:]' \
    | sed -E 's/[[:space:]]+/-/g; s/[^a-z0-9._-]//g; s/^[-.]+|[-.]+$//g')
fi
[ -z "$USERNAME" ] && USERNAME=$(whoami | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9._-]//g')
[ -z "$USERNAME" ] && USERNAME="unknown-user"
DATE=$(date +%Y%m%d)
OUTPUT_FILE=".tessl-insights-poc/reports/agent-logs/${USERNAME}-${DATE}.json"
echo "Contributing as: $USERNAME"
echo "Output: $OUTPUT_FILE"

Tell the user: "I'll save your agent log analysis as <username>. Let me know if you'd like a different name."

Step 3: Analyze Agent Logs

Follow the same analysis approach as the analyze-agent-logs skill:

1. Read the shared references:

   • APEX taxonomy
   • Insight report schema
   • Log discovery guide

   Resolving reference paths: The shared reference links use relative paths (../../references/...) that work when read from the tile directory. If those paths do not resolve (e.g. when activated via a .claude/skills/ symlink), find the shared references at .tessl/tiles/*/agent-insight-experiment/references/ relative to the repository root. For the log discovery guide, if ../analyze-agent-logs/references/log-discovery.md does not resolve, find it at .tessl/tiles/*/agent-insight-experiment/skills/analyze-agent-logs/references/log-discovery.md.

2. Locate agent logs:

   • If logs-path was provided, use it directly — find all .jsonl files under that path and treat them as the input corpus. Skip the standard discovery entirely. Validate the path first:

     if [ -n "$LOGS_PATH" ]; then
       if [ ! -d "$LOGS_PATH" ]; then
         echo "logs-path does not exist: $LOGS_PATH"
         exit 1
       fi
       if ! find "$LOGS_PATH" -type f -name '*.jsonl' -print -quit | grep -q .; then
         echo "No .jsonl files found under: $LOGS_PATH"
         exit 1
       fi
     fi

     A typo or empty export directory should abort the skill — proceeding would produce a misleading empty report that still gets synthesized in.
   • Otherwise, discover agent logs on this machine for the current project using the log-discovery guide.

3. Analyze them for failure patterns, frustration signals, tool usage patterns, and area clustering

4. Produce a report conforming to the insight report schema with prefix LOG

5. Save to the output file determined in Step 2

Set the metadata scan_id by reading it from any existing report in .tessl-insights-poc/reports/:

SCAN_ID=$(cat .tessl-insights-poc/reports/source-code.json 2>/dev/null | grep -oP '"scan_id"\s*:\s*"\K[^"]+' || echo "scan-$(date +%Y%m%d)")

Step 4: Re-run Synthesis

After saving the report, re-run the synthesize-insights skill to update the combined findings and HTML report. This will read all existing reports (including your new contribution) and regenerate findings.json and report.html.

Step 5: Report to User

Tell the user:

1. What was found (brief summary of key insights from their logs)
2. The updated findings are in .tessl-insights-poc/findings.json
3. The updated report is at .tessl-insights-poc/report.html
4. Suggest they commit the changes:

git add .tessl-insights-poc/
git commit -m "Add agent log insights from <username>"

This way other team members can see the updated analysis.