Address Context Findings

Context is the collection of skills and plugins Tessl has observed for a workspace: the copies indexed in the workspace's repositories and the plugins it has published to the registry. Byte-identical copies across places are grouped into one family, so each row is one logical piece of Context with the places it lives.

Findings are specific, actionable observations about that Context. Each Finding concerns a skill instance, a logical (registry) skill, or a repo.

A Finding has:

• archetype: what kind of issue it is (see remediation below).
• priority: critical, high, medium, or low.
• status: active (needs attention), ignored (user set aside), or resolved (no longer on the current scan).
• title / description: what was observed.
• gated: when true, detail is withheld because the owning organization's plan lacks the entitlement; only the Finding type and impacted repos/skills are present. See "Gated Findings" below.

The Findings endpoint resolves each Finding's evidence inline, so the artifacts arrive on the response itself. There is no separate evidence id list to resolve. Read whichever of these fields the Finding populates:

• logicalSkill: the logical (registry) skill the Finding concerns, with canonicalRepo, canonicalName, body, frontmatter, and instanceCount (or null).
• skillInstance: the concrete skill installed or vendored in a repo, with path, body, frontmatter, frontmatterError, and repo details (or null).
• clusterMembers: for overlap, the set of logical skills that cover the same purpose.
• instances: the concrete skill instances the Finding impacts, with repo and path metadata.
• repoFullName / canonicalName: coordinates read directly from the Finding, present even when the detail joins above are gated.

Discovering and calling the API

All raw API mechanics (endpoint paths, query params, response shapes) live in the tessl/api skill. Never restate endpoint schemas or read openapi.json here.

tessl/api is a separate plugin this skill depends on. If it isn't available, install it first with tessl install tessl/api, then proceed.

• Use tessl/api search to find the right endpoint for a task, and show to inspect its params and response.
• Call the endpoint with tessl api ..., which handles auth and headers.

Don't discover or carry a collection id. Context is read per workspace and Findings are read per org, so you resolve identity, not a collection id.

Workflow

1. Resolve the caller's workspace and org. Use tessl/api search/show to find the identity endpoint and the workspace and org listings, call them via tessl api, and match them to the current repo. You need the org id for the Findings endpoint, the workspace id to scope those Findings to this repo, and the workspace name or id for Context.
2. Fetch active Findings for this workspace. Use tessl/api search/show to inspect the org Findings endpoint, then call it via tessl api with the status filter set to active and the workspaceId filter set to the resolved workspace. Scoping to the workspace keeps the results about this repo: an unscoped call returns every workspace's Findings across the org, can expose evidence for unrelated repositories, and is rejected outright for orgs above the endpoint's workspace-count limit. Only widen to an org-wide read (drop workspaceId) when the user explicitly asks for one; treat org-owned Findings with a null workspace and Findings from other workspaces as out of scope for the default current-repo flow. The default sort ranks by priority, so work through them from highest to lowest priority: critical, then high, then medium, then low. Follow the pagination links until they're exhausted, so no Finding is missed. Each row carries workspaceId / workspaceName for drill-down.
3. Handle gated Findings without reconstructing evidence. If a Finding is gated, its detail joins (logicalSkill, skillInstance, clusterMembers) are withheld (see "Gated Findings" below). Report the permitted metadata and move on; do not read the evidence steps below or infer the withheld detail from local files.
4. Read the inline evidence before fixing. For an ungated Finding, each row already carries its artifacts inline (logicalSkill, skillInstance, clusterMembers, instances). Ground the fix in that actual state (the returned body, frontmatter, and path), not the Finding title, then locate those skill files in this repo.
5. Read Context for the wider picture. When a fix needs to know where a skill already lives or whether it's published, read the workspace Context collection via tessl/api. Each row reports states (published, inCodebases), the canonical location, locations counts, and containment (the plugin it belongs to). Filter by kind, provider, repository, or free text, and follow the cursor to page the collection.
6. Re-fetch to confirm. After remediation, re-scan and re-fetch the active Findings for the workspace. A resolved Finding drops off the current scan, so it leaves the active list.

Gated Findings

A Finding is gated when the owning organization's plan lacks the advancedInventoryFindings entitlement and the archetype is one of the gated kinds (drift/overlap). The response withholds the detail joins (logicalSkill, skillInstance, clusterMembers) but still serves the Finding type, priority, and the impacted coordinates (repoFullName, canonicalName, instances).

For a gated Finding:

• Report only the permitted metadata: the archetype, priority, and impacted repos/skills.
• Tell the user the detail is withheld and name what unlocks it: the organization's plan entitlement. Then they can request it.
• Don't run the archetype remediation below, and don't reconstruct the withheld evidence from local paths or other discovery. The gate is a deliberate entitlement boundary, not a data gap to work around.

Remediation by archetype

Apply these only to ungated Findings. For each archetype, read the fields it populates, then apply the fix.

• registry-match: a local skill matches one already in the registry. Compare skillInstance against logicalSkill to confirm the content matches. Replace the local copy with the registry plugin via tessl install.
• drift: an installed skill has diverged from its published source. Diff skillInstance against logicalSkill to see exactly what diverged. If the registry is canonical, re-sync the one owning plugin with a targeted tessl update <workspace/plugin> (identify the plugin from the affected instance's containment; a bare tessl update checks every installed tile and can pull in unrelated updates). If the local edits are intended, republish instead.
• overlap: two or more skills cover the same purpose. Compare the clusterMembers (and their instances) to decide which is canonical. Consolidate into one; merge or remove the duplicates.
• publishable: a useful local skill is not yet shared. Inspect skillInstance to confirm it's registry-ready (clear frontmatter, no repo-specific assumptions). Publish with tessl skill publish.
• frontmatter-error: a SKILL.md has invalid or missing frontmatter. Read skillInstance.frontmatterError and frontmatter to see which field is malformed or missing. Fix name/description and required fields so it parses.
• untracked: a skill exists on disk but isn't declared in tessl.json. Use skillInstance to locate the skill in the repo and confirm it's real. Add it to the manifest so it's managed.
• skill-overload: a repo carries too many skills for an agent to use effectively. Review the repo's instances to see the full set. Prune, merge, or split skills to reduce the count.