factory-triage

Triage a Factory work item's issue — trace history, understand architecture, diagnose root cause, then advance the stage

Quality

71%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./mastracode/factory/factory-skills/factory-triage/SKILL.md

Quality

Content

85%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

This is a highly actionable, well-sequenced operational skill: exact commands, exact tools, explicit validation and retry semantics, and clear decision rules for ambiguous forks. The two weak spots are moderate redundancy around the marker/publication rules and a fully monolithic layout with no progressive disclosure despite content (label tables, grading guides, templates) that would naturally live in reference files.

Suggestions

Move the domain-label table, the severity/effort/impact guides, and the full handoff comment templates into a references/ file (e.g. references/mastra-labels.md, references/handoff-template.md) and link them from the phases, cutting the main file roughly in half.

Deduplicate the marker/publication rules: state the upsert semantics and forbidden alternatives once (Phase 5) and have Phase 1 reference that contract instead of restating it.

Factor the twice-repeated `` table into a single template block referenced by both Phase 1 and the output contract.

Dimension	Reasoning	Score
Conciseness	The body is dense and command-driven with almost no explanation of concepts Claude already knows — every phase is concrete instructions. Minor trimming is possible: the `<!-- mastra-factory-triage -->` marker template appears twice in full, and the `github_upsert_factory_triage_comment` publication rules are explained redundantly in both Phase 1 and Phase 5. It is not 5 because of that repetition.	4 / 5
Actionability	Fully executable throughout: exact commands (`gh issue view <number> --json ...`, `gh issue edit "$ISSUE" --add-label ...`), exact tool names (`github_upsert_factory_triage_comment`, `factory_transition_work_item`, `linear_get_issue`), concrete constraint values (rationale max 1000 chars, `.artifacts/factory-triage/issue-<number>.md`), a ready-to-run bash label-create loop, and explicit anti-patterns (never `gh issue comment`). Specific examples cover the common GitHub and Linear cases.	5 / 5
Workflow Clarity	A clear five-phase sequence with explicit validation checkpoints and feedback loops: fetch the current body/labels/comments before writing the handoff, confirm publication via the tool's returned canonical comment identity, and handle governed-transition rejections by reading the stated reason, re-checking the revision, and retrying exactly once with the reason addressed. Recovery paths are explicit for every risky operation (publication errors, approval_required, revision mismatches).	5 / 5
Progressive Disclosure	Section structure is good (numbered phases, output contract, behavior rules) and there are no broken or deeply nested references, but the skill is a ~200-line single file with zero bundle files — sizable content that would fit a separate reference (the 16-row domain-label table, the severity/effort/impact guides, and the full handoff markdown templates) is inlined. This matches anchor 3 (structure present, content that should be separate is inline) rather than 4, since not even the reference pattern exists.	3 / 5
	Total	17 / 20 Passed

Description

58%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description uses third-person voice, is concise, and names multiple concrete capabilities in a distinct niche. Its main weakness is the absence of any explicit 'use when' trigger guidance, which caps completeness, and its trigger vocabulary leans on internal Factory jargon rather than natural user phrasing.

Suggestions

Append an explicit trigger clause, e.g. "Use when a Factory work item references a GitHub or Linear issue that needs triage, root-cause diagnosis, or a stage-transition decision."

Add natural synonyms users would actually say — "investigate a bug report", "diagnose an issue", "GitHub/Linear issue" — to broaden trigger coverage beyond the internal term "Factory work item".

Optionally surface one more concrete capability (e.g., publishing a structured triage handoff comment) to lift specificity toward full coverage.

Dimension	Reasoning	Score
Specificity	"Triage a Factory work item's issue — trace history, understand architecture, diagnose root cause, then advance the stage" lists several concrete actions (trace history, understand architecture, diagnose root cause, advance the stage) with only minor gaps in coverage. It falls short of 5 because the actions are stated at a summary level without the concrete sub-capacities (e.g., reproduction, labeling, handoff publishing) the skill actually performs.	4 / 5
Completeness	The "what" is clear — triage, trace, diagnose, advance the stage — but there is no "when should Claude use it" clause or equivalent explicit trigger guidance, which caps completeness at 3 per the judging guidelines. It is not 4 because the description never states when to invoke the skill.	3 / 5
Trigger Term Quality	Relevant keywords like "Triage", "issue", "root cause", and "trace history" are present and natural for this domain, but common variations and synonyms (bug report, investigate, diagnose an issue, GitHub/Linear issue) are missing, and "Factory work item" is internal jargon a user would rarely say verbatim. It sits between anchor 3 and 4 but is closer to 3 given the missing natural variations.	3 / 5
Distinctiveness Conflict Risk	"Factory work item's issue" carves out a clear niche with distinct triggers (Factory session, stage transition), giving minimal conflict risk with general debugging or issue-management skills. Not 5 because generic phrases like "trace history" and "diagnose root cause" could weakly overlap with general bug-investigation skills.	4 / 5
	Total	14 / 20 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: mastra-ai/mastra
Path: mastracode/factory/factory-skills/factory-triage/SKILL.md
Commit: 3b0d190

Reviewed: 5 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.