doc-traceability-validator

Validate documentation traceability between code annotations (@implements), feature registry, business rules, and use cases. Detect ID collisions, undocumented features, broken cross-references, and namespace violations.

Quality

75%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.github/skills/doc-traceability-validator/SKILL.md

Quality

Content

75%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 is highly actionable with executable commands and clear workflows supported by real bundle scripts. It is somewhat verbose in its illustrative iteration log and sample output blocks, which slightly reduces token efficiency.

Suggestions

Trim or move the full 'Real-World Example: EdgeQuake Documentation Audit (Iterations 65-75)' narrative and long sample output blocks into a separate reference file to reduce token overhead.

Move the per-script argument tables and output samples into a dedicated scripts reference doc, keeping SKILL.md focused on quick-start and workflow.

Add an explicit validation step (re-run validate_features.py after fixes) to the troubleshooting 'Fix collisions immediately' workflow to strengthen the feedback loop.

Dimension	Reasoning	Score
Conciseness	Mostly efficient with concrete command examples, but includes lengthy sections (e.g., the full real-world iteration log and verbose sample output blocks) that pad the document beyond what Claude needs.	3 / 5
Actionability	Provides fully executable, copy-paste-ready commands and argument tables for every script, covering common validation, generation, and CI/CD integration cases.	5 / 5
Workflow Clarity	Clear multi-step sequences with validation checkpoints (fail-threshold, pre-commit hooks, re-run after fix) and troubleshooting feedback loops, though some flows rely on implicit re-validation.	4 / 5
Progressive Disclosure	Well-organized sections with one-level-deep references to real bundle scripts and related docs; minor gaps since most reference material is inlined rather than split into separate reference files.	4 / 5
	Total	16 / 20 Passed

Description

75%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 is specific and well-differentiated, naming concrete validation actions in a distinct niche. Its main weakness is the absence of an explicit 'Use when' trigger clause, which caps completeness.

Suggestions

Add an explicit 'Use when ...' clause naming the situations that should trigger this skill (e.g., auditing docs, detecting duplicate FEAT/BR/UC IDs, blocking PRs with doc gaps).

Include a few natural synonyms users might say (e.g., 'doc coverage', 'feature registry', 'FEAT IDs') to broaden trigger term coverage.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — validate traceability, detect ID collisions, find undocumented features, broken cross-references, and namespace violations — with comprehensive coverage of the skill's capabilities.	5 / 5
Completeness	Clearly states what the skill does, but there is no explicit 'Use when...' clause or trigger guidance, capping completeness at 3 per the rubric.	3 / 5
Trigger Term Quality	Includes natural terms like 'documentation traceability', 'ID collisions', 'cross-references', and '@implements', but omits common synonyms or file-extension-like variations a user might say.	4 / 5
Distinctiveness Conflict Risk	Occupies a clear niche (documentation traceability between @implements annotations and feature/BR/UC registries) with distinct triggers and minimal conflict risk with other skills.	5 / 5
	Total	17 / 20 Passed

Validation

81%

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 — 13 / 16 Passed

Validation for skill structure

Criteria	Description	Result
metadata_version	'metadata.version' is missing	Warning
metadata_field	'metadata' should map string keys to string values	Warning
relative_links	Relative link issues: 5 suspicious	Warning

	Total	13 / 16 Passed

Repository: raphaelmansuy/edgequake
Path: .github/skills/doc-traceability-validator/SKILL.md
Commit: 4904960

Reviewed: about 20 hours 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.