CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

spec-loop-clarify-task

Engage the User to resolve important open decisions in Spec Loop work, including tasks, plans, design updates, work breakdowns, implementation checkpoints, and ADR drafting. Use when the user asks to clarify, compare options, discuss criteria, or stress-test, or when different answers could materially change scope, behavior, policy, constraints, route, Design, Test specification, or ADR content. Provides mandatory decision screening for workflows that require it before dependent Spec Loop content is written or revised. Also use for general grilling when explicitly selected.

Quality

80%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/spec-loop-clarify-task/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

70%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.

The body delivers an unusually precise, template-driven clarification protocol with concrete formats and clear sequencing, but it is significantly over-long: definitions, enumerations, and format rules are restated multiple times, and dense protocol detail that belongs in reference files is inlined in a single 400-line document. Tightening and splitting would raise both conciseness and organization without losing actionability.

Suggestions

State the 'important open decision' definition and the scope/behavior/policy/route enumeration exactly once (ideally in a definition section) and reference it elsewhere instead of repeating near-verbatim in the description, the opening sections, and the decision tree — this alone would cut substantial length.

Move the fixed clarification-effort question template and the option-line micro-format rules plus their pre-send validation checklist into a references/ file (e.g. references/message-formats.md), keeping only a one-line pointer and the core behavioral rule in SKILL.md.

Merge the duplicated handoff/return rules (Phase and handoff section vs. Resolution scope vs. the workflow-specific returns list) into a single handoff section, and consolidate the storage rules that currently appear under both 'Phase and handoff' and 'Where to store the result'.

DimensionReasoningScore

Conciseness

At ~410 lines the body repeatedly restates the same rules: the "important open decision" definition appears twice in near-verbatim form ("any open question, choice, criterion, trade-off... where different answers could materially change" vs. the description's and decision-tree's restatements), the scope/behavior/policy/route enumeration recurs four-plus times, storage and handoff rules are each stated in multiple sections, and micro-format rules for option lines are specified then re-validated in checklist form. This matches anchor 2 ('several unnecessary explanations or padded sections') — there is real content, but a third or more of the tokens are redundant restatement; it is not anchor 3 because the repetition is pervasive rather than occasional.

2 / 5

Actionability

For an instruction-only skill the guidance is fully concrete and copy-paste ready: fixed templates for decision batches ("Decision 1: <brief answer> (<N>%) / Reason:"), clarification questions ("Question: / Recommended option: <LETTER> (<N>%) / Options: - A. ..."), the effort question with its literal A-D option set, the "Recorded: <choice>." confirmation format, and per-artifact storage rules. Specific examples cover the common cases, matching anchor 5's standard for executable, ready-to-use guidance.

5 / 5

Workflow Clarity

The decision tree (steps 1-5) is explicitly sequenced with recovery paths ("If the point turns out to matter for the design, continue with normal clarification"), and the Exit section provides a verification checklist with the five allowed screening outcomes acting as explicit checkpoints. It falls short of anchor 5 because the overall flow is scattered across seven separately-headed sections (Resolution scope, Phase and handoff, Decision tree, effort question, Step order, storage, Exit) that the reader must mentally assemble into an order, and some checkpoints are implicit rather than inline validation steps.

4 / 5

Progressive Disclosure

The body is well-sectioned with clear headers, and all file references (spec-loop-plan-task, spec-loop-write-adr, spec-loop-implementation-flow, etc.) are clearly signaled, purposeful, and exactly one level deep. However, the skill ships no bundle files and inlines ~400 lines of protocol detail — the fixed effort-question template, the option-line micro-format rules and their validation checklist, and the per-artifact storage rules — that plausibly belongs in a references/ file, matching anchor 3's 'content that should be separate is inline' despite good section structure.

3 / 5

Total

14

/

20

Passed

Description

83%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.

A strong description that explicitly covers what the skill does, when to use it with concrete trigger phrases, and how it differs from free-form discussion. Its main limitation is reliance on project-specific jargon (Spec Loop, ADR, decision screening) that slightly narrows the natural-language trigger surface.

DimensionReasoningScore

Specificity

The description names the domain (Spec Loop work) and several concrete actions: "Engage the User to resolve important open decisions", "mandatory decision screening", "clarify, compare options, discuss criteria, or stress-test", covering tasks, plans, design updates, work breakdowns, checkpoints, and ADR drafting. It falls short of anchor 5 because the actions all describe one activity (resolving decisions) rather than a comprehensive set of distinct capabilities, but it clearly exceeds anchor 3's '1-2 concrete actions' via the enumerated decision domains and screening mechanism.

4 / 5

Completeness

Both 'what' and 'when' are explicitly answered with concrete trigger phrases: what — "Engage the User to resolve important open decisions... Provides mandatory decision screening"; when — "Use when the user asks to clarify, compare options, discuss criteria, or stress-test, or when different answers could materially change scope, behavior, policy, constraints, route, Design, Test specification, or ADR content". This matches the anchor 5 pattern of explicit what + explicit when with concrete trigger phrases; anchor 4's 'when could be more explicit' does not apply since the when-clause is highly specific.

5 / 5

Trigger Term Quality

It includes natural phrases users would say — "asks to clarify, compare options, discuss criteria, or stress-test" and "general grilling when explicitly selected" — plus a materiality trigger clause. It does not reach anchor 5 because much of the vocabulary is project jargon ("Spec Loop", "ADR drafting", "decision screening", "governing artifact") that a user would rarely say verbatim, and synonyms like 'decide', 'align', or 'pressure-test' are absent.

4 / 5

Distinctiveness Conflict Risk

The "Spec Loop" framing ties the skill to a specific workflow family with distinct triggers (decision screening, ADR clarification, implementation checkpoints), and it explicitly scopes itself against a "generic grill-me variant or free-form discussion". It stays at 4 rather than 5 because broad triggers like "clarify" and "discuss criteria" could overlap with general discussion or planning skills outside the Spec Loop family.

4 / 5

Total

17

/

20

Passed

Validation

93%

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

Validation — 15 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

relative_links

Relative link issues: 8 suspicious

Warning

Total

15

/

16

Passed

Repository

dpolivaev/spec-loop

Path

skills/spec-loop-clarify-task/SKILL.md

Reviewed

Table of Contents

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.