architecture-decision

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

Quality

62%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./skills/architecture-decision/SKILL.md

Quality

Discovery

40%

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 identifies a clear niche (architectural decision records) and mentions specific artifacts (Hindsight, CLAUDE.md), giving it good distinctiveness. However, it lacks an explicit 'Use when...' clause and misses common trigger terms users might naturally use (e.g., 'ADR', 'design decision'). The actions described are somewhat vague about what the skill concretely does beyond recording a decision.

Suggestions

Add an explicit 'Use when...' clause, e.g., 'Use when the user wants to record an architectural decision, asks about ADRs, or needs to document a design choice or technical tradeoff.'

Include natural trigger term variations such as 'ADR', 'architecture decision record', 'design decision', 'technical tradeoff', 'why we chose'.

Be more specific about the concrete actions, e.g., 'Creates a structured ADR document with context, options considered, decision, and consequences; saves it to Hindsight for future reference; updates CLAUDE.md project guidelines if the decision affects development practices.'

Dimension	Reasoning	Score
Specificity	Names the domain (architectural decisions) and some actions (record decision/rationale, retain into Hindsight, update CLAUDE.md), but the actions are somewhat vague — 'retain into Hindsight' and 'update CLAUDE.md if needed' lack detail about what those steps concretely involve.	2 / 3
Completeness	Describes what it does (document an architectural decision, record rationale, retain into Hindsight, update CLAUDE.md) but has no explicit 'Use when...' clause or equivalent trigger guidance, which per the rubric caps completeness at 2 — and the 'what' is also only moderately clear, pushing this toward 1.	1 / 3
Trigger Term Quality	Includes relevant terms like 'architectural decision' and 'rationale', but misses common variations users might say such as 'ADR', 'architecture decision record', 'design decision', 'technical decision', or 'why did we choose'. 'Hindsight' and 'CLAUDE.md' are tool-specific terms rather than natural user language.	2 / 3
Distinctiveness Conflict Risk	The combination of 'architectural decision', 'Hindsight', and 'CLAUDE.md' creates a very specific niche that is unlikely to conflict with other skills. The scope is narrow and well-defined.	3 / 3
	Total	8 / 12 Passed

Implementation

85%

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

This is a well-structured skill that provides a clear, actionable workflow for documenting architectural decisions. The ADR template is concrete and complete, the workflow includes appropriate validation gates (user review, approval before CLAUDE.md changes), and the content is organized logically. Minor verbosity in framing text prevents a perfect conciseness score, but overall this is a strong skill.

Dimension	Reasoning	Score
Conciseness	The content is mostly efficient but includes some unnecessary explanation. The 'Important' section's note about constraints vs decisions is a nice touch but slightly verbose. The step descriptions could be tighter — e.g., 'Parse the decision' elaboration bullets are useful but the framing text around them adds minor bloat.	2 / 3
Actionability	The skill provides a concrete ADR template with specific fields, clear step-by-step instructions including tool usage (Hindsight retain), and a confirmation output template. Each step specifies exactly what to do, including when to ask the user for more information and what to check in CLAUDE.md.	3 / 3
Workflow Clarity	The 6-step workflow is clearly sequenced with explicit checkpoints: user review/approval at step 3, user approval before CLAUDE.md update at step 5, and a confirmation summary at step 6. The flow includes appropriate gates (present for review before retaining, only update CLAUDE.md with approval).	3 / 3
Progressive Disclosure	For a skill of this size and complexity (~60 lines, single workflow), the content is well-organized with clear sections (Steps, Important) and doesn't need external references. The inline ADR template and confirmation template are appropriately placed rather than split into separate files.	3 / 3
	Total	11 / 12 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 — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: AndreJorgeLopes/devflow
Commit: b0b1bb6

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