CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

architectural-decisions

Use when a task asks why code is built a certain way, proposes architectural changes, compares implementation approaches, or mentions decision markers such as WHY, DECISION, TRADEOFF, or ADR in a Repowise-indexed repository.

Quality

77%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

Fix and improve this skill with Tessl

tessl review fix ./plugins/codex/skills/architectural-decisions/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

82%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 lean, highly actionable instruction skill: every workflow is keyed to a concrete trigger and backed by copy-paste-ready tool and CLI invocations with example arguments. The only notable weakness is the single dense 'Reviewing candidates' paragraph, which buries several commands and would benefit from a list or sub-structure.

DimensionReasoningScore

Conciseness

The body is efficient and assumes competence — "`get_why` has four modes — pick by what you pass", no explanations of concepts Claude already knows. Not 5: the 'Reviewing candidates' section is one dense paragraph packing seven commands and could be trimmed or split.

4 / 5

Actionability

Fully executable, copy-paste-ready guidance: `get_why(query="why is auth using JWT?")` with all four call modes shown concretely, and complete CLI invocations like `repowise decision add --agent <your slug> --title "..." --decision "..." --rationale "<why, and what you rejected>" --affects <path>` and `repowise decision confirm <id> --agent <your slug> --evidence <commit|file>` covering the common cases.

5 / 5

Workflow Clarity

Scenario-keyed sections give clear sequences, e.g. "1. Call `get_why(query="the specific area you're changing")`... 2. If decisions are found, present them to the user before proceeding... 3. If no decisions are found, proceed but note..." — a real checkpoint, plus refusal handling ("If the repository turned agent acceptance off, the confirm is refused; leave it for a person"). Not 5: the candidates-review flow is prose rather than a sequenced list and its checkpoints (checking `blockers`, resolving, confirming) are implicit.

4 / 5

Progressive Disclosure

No bundle files exist and none are needed; the ~61-line body is organized into clear, well-labeled sections keyed to usage triggers, which is good structure. Not 5: it sits just above the simple-skill (~50-line) range and the monolithic 'Reviewing candidates' paragraph is a candidate for being broken out or restructured.

4 / 5

Total

17

/

20

Passed

Description

61%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, natural trigger clause with a distinctive niche (Repowise, decision markers), undermined by never stating what the skill actually does. Adding a short capability statement (e.g., retrieving and recording architectural decision records) would raise completeness and specificity.

Suggestions

Prepend a concrete capability statement before the 'Use when' clause, e.g., 'Retrieves and records architectural decision records (the why behind code) via Repowise. Use when...' — this fixes the missing 'what' that caps completeness.

Add natural synonyms users would say, such as 'design decisions', 'rationale', or 'trade-offs', to broaden trigger-term coverage.

Tighten the broad triggers 'proposes architectural changes, compares implementation approaches' toward the decision-record context (e.g., 'proposes changes that contradict or build on recorded decisions') to reduce overlap with generic code-review skills.

DimensionReasoningScore

Specificity

The description names the domain and concrete trigger scenarios ("asks why code is built a certain way", "proposes architectural changes", "compares implementation approaches"), but no capability actions are ever stated — there is no 'what the skill does' equivalent to 'extract text and fill forms'. This matches anchor 3 (domain plus some concrete elements, not comprehensive) rather than 4, which requires several specific actions.

3 / 5

Completeness

The 'when' is explicit and detailed ("Use when a task asks why..."), but the 'what' is never stated — the capability of the skill is only inferable. Anchor 2 ("only 'when' is present without 'what'") fits textually, but the domain-specific, multi-clause 'when' with named markers keeps it above that level; anchor 4 requires both what and when explicitly, which is not met.

3 / 5

Trigger Term Quality

Good natural-term coverage: "why code is built a certain way", "architectural changes", "compares implementation approaches", plus literal markers "WHY, DECISION, TRADEOFF, or ADR". Not 5 because common synonyms a user would actually say — 'design decisions', 'rationale', 'trade-offs', 'refactor' — are missing.

4 / 5

Distinctiveness Conflict Risk

"in a Repowise-indexed repository" and the marker list ("WHY, DECISION, TRADEOFF, or ADR") create a clear niche, but "proposes architectural changes, compares implementation approaches" are broad triggers that overlap general design-review and code-review skills — minor conflict risk, matching anchor 4.

4 / 5

Total

14

/

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

repowise-dev/repowise

Path

plugins/codex/skills/architectural-decisions/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.