CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

adr-discipline

Use before proposing any architectural, modelling, or dependency decision; after making one; or when tempted to restructure existing code whose shape seems wrong. ADRs are the memory that stops agents from relitigating settled decisions across sessions.

Quality

78%

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 ./.claude/skills/adr-discipline/SKILL.md
SKILL.md
Quality
Evals
Security

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.

A well-crafted, opinionated instruction skill: concrete commands, an explicit decision tree, and sharp guidance on what deserves an ADR versus a commit-body record. Weaknesses are minor — some repetition in the lightweight-mode section, jargon borrowed from sibling skills ('bead', 'quality-gates'), and no verification step after writing an ADR.

DimensionReasoningScore

Conciseness

The body is dense, opinionated, and project-specific with no explanation of concepts Claude already knows; the only trimmable spots are the lightweight-mode section restating its graduation rule twice ('The moment a decision constrains future structure... graduates to a real ADR file' followed by 'Scoped-to-one-bead → commit body + bead link. Load-bearing beyond the bead → ADR.'), matching 'efficient; minor instances of over-explanation that could be trimmed' rather than the every-token-earns-its-place level.

4 / 5

Actionability

Guidance is concrete and executable: a copy-paste search command (`rg -il '<topic keywords>' docs/adr/`), a three-branch decision tree, a file naming convention (`docs/adr/NNNN-short-title.md`), a template reference, and an explicit status lifecycle. Minor gaps — the unexplained 'quality-gates' parenthetical and 'bead/tracker-state' jargon that assume context from other skills — keep it below fully-executable coverage.

4 / 5

Workflow Clarity

The pre-proposal workflow is a clear sequence with explicit branch checkpoints (accepted ADR → work within it; consistent shape → follow and backfill; genuinely new → decide and record), and the writing section specifies structure and statuses. There is no post-write verification step (e.g. confirming sequential numbering or that links resolve), so it sits at 'clear sequence with most checkpoints present' rather than the explicit-validation level.

4 / 5

Progressive Disclosure

No bundle files exist (references/, scripts/, assets/ are absent) and the body's file references point to project paths (docs/adr/, templates/adr.md, specs/). The single file is well-sectioned with clear headers and appropriate for its size (~83 lines); the only organization gap is the lengthy lightweight-mode section, which is the one candidate for extraction into a reference file.

4 / 5

Total

16

/

20

Passed

Description

70%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, trigger-rich description with unusually explicit 'when' guidance covering three distinct usage moments. Its main weakness is that the 'what' is expressed only as purpose ('ADRs are the memory...') rather than as concrete skill actions, leaving a reader to infer what the skill actually does.

Suggestions

State the skill's concrete actions explicitly, e.g. 'Searches docs/adr/ for existing decisions, records new ones from a template, and supersedes accepted ADRs rather than editing them.'

Add common synonyms for the restructure trigger — 'refactor' and 'design decision' — to catch natural user phrasings the current wording misses.

DimensionReasoningScore

Specificity

The description names the domain clearly ('architectural, modelling, or dependency decision', 'ADRs') and conveys purpose ('the memory that stops agents from relitigating settled decisions'), but never states the skill's concrete actions such as searching existing ADRs, writing one, or superseding — matching the 'names domain and 1-2 concrete actions, but not comprehensive' anchor.

3 / 5

Completeness

'When' is explicit and triple-specified ('Use before proposing...; after making one; or when tempted to restructure...'), and 'what' is present via the ADR-as-memory purpose statement, but the 'what' is purpose-framed rather than action-explicit, matching the anchor where both exist yet one could be more specific.

4 / 5

Trigger Term Quality

Natural trigger phrases are well covered ('proposing any architectural, modelling, or dependency decision', 'restructure existing code', 'ADRs'), but common synonyms a user would plausibly say — 'refactor', 'design decision' — are missing, fitting the 'good keyword coverage; a few natural terms missing' anchor.

4 / 5

Distinctiveness Conflict Risk

ADR discipline is a distinct niche with domain-specific triggers ('ADR', 'relitigating settled decisions'), but the broad 'before proposing any architectural... decision' trigger could overlap with planning or design-review skills, fitting 'mostly distinct; minor overlap risk with closely related skills'.

4 / 5

Total

15

/

20

Passed

Validation

100%

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

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

igouss/gitweb-rs

Path

.claude/skills/adr-discipline/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.