Run Insight Scan

Orchestrate a scan that surfaces actionable findings about how a repository affects coding agent performance, and recommends concrete actions to improve it.

The scan runs in two phases:

1. Phase 1 — Six analyzers examine the repository through different data source lenses, each producing a structured report of findings (without actions)
2. Phase 2 — A synthesis step cross-references all reports, deduplicates findings, generates targeted actions for each finding (with Tessl product awareness), and produces an HTML report

Prerequisites

• The target repository must be a git checkout (for git history analysis)
• gh CLI installed and either (a) authenticated via gh auth login with GH_TOKEN exported from your shell profile, or (b) GH_TOKEN / GITHUB_TOKEN set directly. On macOS, Cursor's sandbox can't read the gh keychain, so the env var is effectively required — add export GH_TOKEN="$(gh auth token)" to ~/.zshrc (or ~/.bashrc) once and restart Cursor. See the analyze-github-data skill's "Troubleshooting: sandboxed gh" section for details.
• Agent conversation logs should exist on the machine (for agent log analysis — optional but recommended)
• Subagent capability is strongly recommended for parallel execution of analyzers; synthesis always runs in the main session

Setup

Run the initialization script to create directories, resolve metadata, and check prerequisites in one step:

SCAN_CONFIG=$(bash "$(dirname "$0")/scripts/init-scan.sh" --root "$(pwd)")

Resolving script path: The path above assumes this skill is read from its tile directory. If run via a .claude/skills/ symlink, locate the script at .tessl/tiles/*/agent-insight-experiment/skills/run-insight-scan/scripts/init-scan.sh relative to the repo root, or pass --username <name> to override the username.

Parse the output to extract variables for the analyzers:

SCAN_ID=$(echo "$SCAN_CONFIG" | grep -o '"scan_id": *"[^"]*"' | cut -d'"' -f4)
INSIGHTS_DIR=$(echo "$SCAN_CONFIG" | grep -o '"insights_dir": *"[^"]*"' | cut -d'"' -f4)
REPO_NAME=$(echo "$SCAN_CONFIG" | grep -o '"repo_name": *"[^"]*"' | cut -d'"' -f4)
USERNAME=$(echo "$SCAN_CONFIG" | grep -o '"username": *"[^"]*"' | cut -d'"' -f4)

The script creates the output directory tree ($INSIGHTS_DIR/reports/agent-logs/), checks for git, gh, node, and python3, and outputs all resolved paths as JSON. Pass the full SCAN_CONFIG JSON to each analyzer so they know their output paths.

Manual Setup (Fallback)

If the script is unavailable, create the structure manually:

INSIGHTS_DIR="$(pwd)/.tessl-insights-poc"
mkdir -p "$INSIGHTS_DIR/reports/agent-logs"
SCAN_ID="scan-$(date +%Y%m%d-%H%M%S)"
REPO_NAME="$(git remote get-url origin 2>/dev/null | sed 's/.*[:/]\([^/]*\/[^/]*\)\.git$/\1/' || basename "$(pwd)")"

Phase 1: Parallel Data Source Analysis

Each analyzer should run as a separate subagent, not in the main session. If subagents are available, launch all six simultaneously in parallel. The main session's only job during Phase 1 is to dispatch the analyzers and wait for their results — do not run analyzer logic inline. If subagents are not available, see Fallback: Manual Orchestration.

Before launching the analyzers, read the shared reference files so you can provide their contents as context to each analyzer:

• APEX taxonomy — the insight taxonomy
• Insight report schema — the report format each analyzer must produce

Resolving reference paths: The links above use relative paths (../../references/...) that work when this skill is read from its 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.

Each analyzer receives these parameters:

• scan_id: The shared scan ID
• repository: The repository name
• output_file: Where to save its report (paths below)
• The full contents of the APEX taxonomy and insight report schema (read and embed these — don't just pass the paths, since analyzers running as subagents may not be able to resolve them)

Analyzer 1: Source Code

Skill: analyze-source-code Output: $INSIGHTS_DIR/reports/source-code.json

Examines the application/business logic code, tests, build configuration, and dependency setup.

Analyzer 2: Git History

Skill: analyze-git-history Output: $INSIGHTS_DIR/reports/git-history.json

Examines commit history, file churn, contributor patterns, co-change relationships, and revert frequency.

Analyzer 3: GitHub Data

Skill: analyze-github-data Output: $INSIGHTS_DIR/reports/github-data.json

Examines pull requests, review comments, CI/CD history, and issues via the gh CLI.

Analyzer 4: Agent Logs

Skill: analyze-agent-logs Output: $INSIGHTS_DIR/reports/agent-logs/<username>-<date>.json

Examines agent conversation histories from Cursor, Claude Code, or other tools. Resolve the username for the filename (caller may pass username= to override):

# Explicit input wins over the git/whoami fallback.
USERNAME="${USERNAME_INPUT:-}"
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)

Pass the full output_file path to the analyzer — it will use exactly that path and not resolve its own.

Analyzer 5: Agent Context & Configuration

Skill: analyze-agent-context Output: $INSIGHTS_DIR/reports/agent-context.json

Examines existing agent configuration: .cursor/rules, AGENTS.md, CLAUDE.md, .claude/ files, MCP configurations, and other agent-facing context files.

Analyzer 6: Context Inventory

Skill: analyze-context-inventory Output: $INSIGHTS_DIR/reports/context-inventory.json

Produces a per-file inventory of every markdown and config file agents consume — classified by category (entry point / always-on rule / hook / skill / MCP), agent harness (Claude / Cursor / cross-agent), and usefulness. Complements analyze-agent-context: the former emits qualitative insights, this one emits the structured catalogue that renders as a filterable file tree in the HTML report.

Analyzer Write Permissions

Each analyzer should write its report JSON to the output_file path. If an analyzer does not have write permissions (e.g. due to sandboxing), it must return its complete report as structured JSON in its response to the main session. The main session then writes the file on its behalf:

# When dispatching each analyzer, include in its instructions:
"If you cannot write to the output file, return the full JSON report in your
response so the orchestrator can write it for you. Do NOT summarize — return
the full JSON."

Waiting for Analyzer Completion

After launching all six analyzers, you MUST wait for every one to return before proceeding to Phase 2. Do NOT assume analyzers have finished. Do NOT start synthesis until all six are resolved.

As each analyzer returns, check its result:

1. Succeeded and wrote its report file — done.
2. Succeeded but returned the report inline (couldn't write to disk) — write the file yourself in the main session.
3. Failed (permission error, empty result, or error message instead of a report) — retry that analyzer's work directly in the main session. Do NOT launch another subagent for it. The main session has full tool permissions.

If an analyzer cannot produce results at all (e.g. no agent logs exist on this machine), note which data source is missing — synthesis needs to know.

Once all six are resolved, verify:

ls -la "$INSIGHTS_DIR"/reports/*.json "$INSIGHTS_DIR"/reports/agent-logs/*.json 2>/dev/null | wc -l

Phase 2: Synthesis

Do NOT start this phase until every analyzer from Phase 1 has returned and been handled.

Once all reports are ready, run synthesis in the main session — do NOT launch it as a background task or subagent.

Synthesis depends on all six analyzer reports existing before it can start, so it cannot be launched in parallel with them. Running it inline in the main session means it naturally starts only after all analyzers have completed and the main session has confirmed their outputs exist.

Invoke the synthesize-insights skill directly in the main session.

The synthesizer gets:

• All report files from $INSIGHTS_DIR/reports/
• Full access to all data sources (for cross-referencing and validation)
• The shared taxonomy, report schema, and findings schema references

It produces:

• $INSIGHTS_DIR/findings.json — synthesized findings with inline actions, an overall score (blocked | constrained | productive), and an executive summary
• $INSIGHTS_DIR/report.html — standalone HTML report for sharing

Presenting Results

After Phase 2 completes:

1. Lead with the overall_score.level and the executive_summary — this is the 30-second read
2. Then surface the top findings (highest priority score)
3. Highlight quick wins — findings with pebble or stone-sized actions
4. Note which data sources contributed most findings
5. Recommend the user commits .tessl-insights-poc/ to git
6. Suggest team members run contribute-agent-logs to add their perspective

open "$INSIGHTS_DIR/report.html"

Fallback: Manual Orchestration

If subagents aren't available, provide the user with instructions to run each analyzer as a separate skill invocation:

1. "Run the analyze-source-code skill and save results to .tessl-insights-poc/reports/source-code.json"
2. "Run the analyze-git-history skill and save results to .tessl-insights-poc/reports/git-history.json"
3. "Run the analyze-github-data skill and save results to .tessl-insights-poc/reports/github-data.json"
4. "Run the analyze-agent-logs skill and save results to .tessl-insights-poc/reports/agent-logs/<username>-<date>.json"
5. "Run the analyze-agent-context skill and save results to .tessl-insights-poc/reports/agent-context.json"
6. "Run the analyze-context-inventory skill and save results to .tessl-insights-poc/reports/context-inventory.json"
7. "Once all reports are ready, run the synthesize-insights skill in this session (not as a background task)"

Each skill is designed to work standalone — the orchestrator is a convenience, not a requirement. Synthesis must always run in the main session since it depends on all analyzer reports being complete first.