architecture-decision

Document an architectural decision — record the decision and rationale, retain into Hindsight, and update CLAUDE.md if needed.

Quality

—

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Quality

Content

77%

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 a strong, checkpointed workflow and a reusable template, but it carries a fairly long diagram aside that pads the overview. Tightening or externalizing the diagram material would improve conciseness and progressive disclosure.

Suggestions

Move the diagram-complexity rating block and the optional-diagram paragraph into a short separate reference or condense it, so the main overview stays lean.

Trim the embed-syntax code block to a single line since the alt-text guidance is the only essential detail.

Consider a one-line 'When to draw a diagram' trigger rather than the full green/yellow/red taxonomy inline.

Dimension	Reasoning	Score
Conciseness	Mostly efficient and assumes Claude's competence, but the diagram-complexity block and the optional diagram-instruction paragraph add length that is peripheral to the core ADR workflow.	2 / 3
Actionability	Provides a complete, copy-paste-ready ADR template with named fields, concrete embed syntax, and exact retain-tool field mappings — fully executable guidance.	3 / 3
Workflow Clarity	Six clearly sequenced steps with explicit checkpoints: user-approval gate before presenting, Hindsight retain step, and a user-approval checkpoint before CLAUDE.md is updated.	3 / 3
Progressive Disclosure	Well-organized into sections with no bundle files (so no nested references), but the diagram guidance is a substantial inline aside that could be split out for a cleaner overview.	2 / 3
	Total	10 / 12 Passed

Description

67%

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 names a concrete domain and several specific actions with a distinct niche, but it omits an explicit 'Use when...' trigger and under-covers natural terminology variations. Adding a usage trigger and synonyms would lift the two weaker dimensions.

Suggestions

Add an explicit trigger clause such as 'Use when documenting an architectural decision, writing an ADR, or finalizing a major design choice.'

Include common user phrasings like 'ADR', 'decision record', and 'architecture decision record' to improve trigger-term coverage.

Keep the existing concrete actions but pair them with the 'when' so both what and when are explicit.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions: 'record the decision and rationale, retain into Hindsight, and update CLAUDE.md if needed' — names domain (architectural decisions) and specific downstream actions.	3 / 3
Completeness	Clearly states what the skill does, but the 'when' is only implied — there is no explicit 'Use when...' clause, which per the rubric caps completeness at 2.	2 / 3
Trigger Term Quality	Terms like 'architectural decision' and 'CLAUDE.md' are natural to a developer audience but coverage of common variations ('ADR', 'decision record', 'architecture choice') is thin.	2 / 3
Distinctiveness Conflict Risk	The Hindsight retain + CLAUDE.md update niche is a clear, distinct workflow unlikely to be confused with other skills.	3 / 3
	Total	10 / 12 Passed

Validation

93%

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

Validation for skill structure

Criteria	Description	Result
relative_links	Relative link issues: 1 missing	Warning

	Total	15 / 16 Passed

Repository: AndreJorgeLopes/devflow
Commit: 9556c94

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