reverse-engineering

Brownfield entry point for the V-Model workflow. Reverse-engineers an existing codebase into the standard V-Model artifacts: plan-context.md, ADRs, arc42 snapshot, FEATURE inventory, backlog seed, and an evidence-based BA draft. Walks the V backwards from Coding up to Business Analysis, filling every step only with what can be proven from the code or the existing documentation. Every claim is sourced (path:line or doc section); nothing is invented. Use this skill when the user mentions "existing project", "legacy codebase", "reverse engineer", "import existing code", "brownfield", "we already have code", "onboard existing project", or when the user wants to enter the V-Model workflow but artifacts do not exist yet.

Quality

78%

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 ./skills/reverse-engineering/SKILL.md

Quality

Content

56%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 comprehensive, well-structured brownfield reverse-engineering workflow with strong actionability and clear phase sequencing. Its main weakness is verbosity—the skill tries to be both a reference manual and an instruction set, resulting in significant length that could be reduced by 40-50% through deduplication, removing explanations of obvious concepts, and offloading detailed sub-phases to reference files. The out-of-order Phase 6/9 placement is a notable structural issue.

Suggestions

Reduce verbosity by stating each rule exactly once—remove duplicate explanations of source-per-claim, status defaults, and anti-hallucination rules that appear in multiple sections. Target cutting 40% of content.

Move Phase -1.5 migration mechanics, Phase 9 parallel-branch alignment, and the detailed Phase 7 verification block format into separate reference files, keeping only summaries in SKILL.md.

Fix the Phase ordering: Phase 6 (Handoff Ritual) content appears after Phase 9 in the document body, which contradicts the numbered sequence and creates confusion.

Provide bundle files for the referenced templates (BACKLOG-TEMPLATE.md, BA-TEMPLATE.md, FEATURE-TEMPLATE.md, EPIC-TEMPLATE.md) or inline minimal versions so the skill is self-contained.

Dimension	Reasoning	Score
Conciseness	The skill is extremely long (~600+ lines) with significant repetition and over-explanation. Multiple sections restate the same rules (e.g., anti-hallucination rules, source-per-claim, status defaults). The backlog status defaults table, phase-schema explanations, and migration sub-phases add substantial bulk. Claude doesn't need explanations of what TODOs/FIXMEs are or why evidence matters—it needs the rules stated once, concisely.	2 / 5
Actionability	The skill provides concrete file paths, directory structures, YAML frontmatter examples, bash commands, template formats, and specific artifact naming conventions. Most phases have executable guidance with copy-paste-ready snippets. Minor gaps exist—some phases reference external templates and tools (e.g., `flow.py`, `BACKLOG-TEMPLATE.md`, `BA-TEMPLATE.md`) without showing their content, and some steps are procedural descriptions rather than executable commands.	4 / 5
Workflow Clarity	The multi-phase workflow (Phase -1 through Phase 9) is clearly sequenced with explicit phase numbering and dependencies. Quality gates at the end serve as validation checkpoints. However, Phase 6 is listed out of order (appears after Phase 9 in the document despite being numbered 6), which is confusing. The Phase 7 verification gate provides good feedback loops for drift detection. Minor gap: no explicit error recovery if a quality gate fails beyond 'fix any failed gate.'	4 / 5
Progressive Disclosure	The skill references many external files (templates, team-workflow.md, branch-protection.md, canonical-specs, BACKLOG-TEMPLATE.md, BA-TEMPLATE.md, FEATURE-TEMPLATE.md, EPIC-TEMPLATE.md) which is good progressive disclosure in principle. However, no bundle files are provided, making it impossible to verify these references resolve. The skill itself is monolithic—Phase -1.5 migration details, the full verification block format, and the parallel-branch alignment steps could reasonably live in separate reference files. The content that is inline is too long for a single SKILL.md.	3 / 5
	Total	13 / 20 Passed

Description

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

This is an excellent skill description that clearly articulates what the skill does (reverse-engineers existing codebases into specific V-Model artifacts), how it does it (evidence-based, sourced claims), and when to use it (comprehensive list of natural trigger phrases). It uses proper third-person voice throughout and provides enough specificity to be easily distinguishable from other skills.

Dimension	Reasoning	Score
Specificity	The description lists multiple specific concrete actions: reverse-engineers a codebase, produces plan-context.md, ADRs, arc42 snapshot, FEATURE inventory, backlog seed, and BA draft. It also specifies the methodology (walking the V backwards from Coding to Business Analysis) and the sourcing constraint (path:line or doc section).	5 / 5
Completeness	Clearly and explicitly answers both 'what' (reverse-engineers codebase into specific V-Model artifacts with evidence-based sourcing) and 'when' (explicit 'Use this skill when...' clause with multiple concrete trigger phrases). Both dimensions are thoroughly covered.	5 / 5
Trigger Term Quality	Comprehensive coverage of natural trigger terms including 'existing project', 'legacy codebase', 'reverse engineer', 'import existing code', 'brownfield', 'we already have code', 'onboard existing project', and the contextual trigger 'artifacts do not exist yet'. These are phrases users would naturally say.	5 / 5
Distinctiveness Conflict Risk	Highly distinctive with a clear niche: brownfield/reverse-engineering entry into a specific V-Model workflow. The combination of 'brownfield', 'reverse engineer', specific artifact names (arc42, ADRs, FEATURE inventory), and the evidence-based constraint makes it very unlikely to conflict with other skills.	5 / 5
	Total	20 / 20 Passed

Validation

90%

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 — 10 / 11 Passed

Validation for skill structure

Criteria	Description	Result
skill_md_line_count	SKILL.md is long (838 lines); consider splitting into references/ and linking	Warning

	Total	10 / 11 Passed

Repository: salemaziel/digital-innovation-agents
Path: skills/reverse-engineering/SKILL.md
Commit: 055b016

Reviewed: 10 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.