Generate Actions for Findings

You receive a set of deduplicated, prioritized findings from an insight scan. Your job is to generate a targeted, specific action for each finding — the single best recommendation for addressing that finding.

Before You Start

Read the shared reference files:

• Tessl product context — when to recommend plugins vs simpler fixes
• Findings schema — the action object shape and valid action types

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.

Inputs

You receive findings as a JSON array (via a temp file or inline in your prompt). Each finding has:

• id, category, subcategory, title, description
• evidence[] with locations and details
• impact and effort scores
• data_sources[]

The findings do not yet have an action field — that's what you're generating.

Action Generation Strategy

Step 1: Read All Findings First

Before generating any actions, read through every finding to understand the full picture. This helps you:

• Spot clusters of related findings that might benefit from a single plugin
• Avoid recommending the same simple fix repeatedly when a plugin would be more appropriate
• Calibrate effort estimates consistently across findings

Step 2: For Each Finding, Generate an Action

For each finding, produce an action object:

{
  "title": "<concise imperative — what to do>",
  "description": "<why this helps and what it involves>",
  "type": "<one of the valid action types>",
  "effort_size": "<pebble | stone | rock | boulder>",
  "example_fix": "<optional — concrete example>"
}

Step 3: Choose the Right Action Type

Consult tessl-product-context.md for the full decision framework. Key heuristics:

Prefer create_plugin when:

• The finding reveals a knowledge gap about an internal library, framework, or domain that needs structured documentation, skills, and rules packaged together
• Multiple findings cluster around the same area and would all benefit from a single plugin
• The knowledge is reusable across repositories
• The fix involves both "what to know" (docs/rules) and "how to do it" (skills)

Prefer update_plugin when:

• A plugin is already installed but is outdated, misconfigured, or missing coverage for the area the finding describes

Prefer remove_plugin when:

• A plugin is installed but its rules conflict with the codebase, it duplicates other context, or it provides stale guidance

Prefer simpler types (add_rule, create_context, add_docs, etc.) when:

• The fix is a single convention, a one-liner rule, or a repo-specific note
• The knowledge doesn't benefit from versioning or packaging
• The fix is small enough that creating a plugin would be over-engineering

Prefer code-level types (update_code, refactor, add_tests) when:

• The problem is in the code itself, not in missing agent context

Step 4: Write Specific, Actionable Descriptions

Bad: "Add documentation for the auth library." Good: "Create a Tessl plugin for packages/auth with: (1) a skill for the login/logout flow, (2) rules for token refresh patterns, (3) API docs covering all 12 exported functions. Install via tessl.json so all team members' agents get the context automatically."

Bad: "Fix the inconsistent naming." Good: "Add a rule to .cursor/rules/naming.md specifying that all API route handlers use camelCase and all database column names use snake_case. Reference the existing patterns in apps/backend/src/routes/ as the canonical examples."

Step 5: Calibrate Effort Sizes

Use rock sizing consistently:

A create_plugin action is typically a rock (basic plugin) or boulder (plugin with comprehensive evals and multiple skills). A simple add_rule is a pebble or stone.

Output

Return the findings array with each finding now containing an action field. Write the result to the same temp file path you received, or return it inline if working within a subagent context.

Do not modify any other fields on the findings — only add the action object.

Validation

Before returning:

• Every finding has an action with all required fields (title, description, type, effort_size)
• Action type values are from the valid set in findings-schema.md
• effort_size values are valid rock sizes
• Descriptions are specific and actionable, not generic
• Plugin-related actions (create_plugin, update_plugin, remove_plugin) are used appropriately per tessl-product-context.md