architectural-proposals

How to write comprehensive architectural proposals that drive alignment before code is written

Quality

57%

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 ./.squad-templates/skills/architectural-proposals/SKILL.md

Quality

Content

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

The body is well-organized with concrete, actionable templates and worked examples appropriate to an instruction-only skill. Its main weaknesses are some redundancy between sections and a proposal-writing workflow that is implied across patterns rather than presented as one explicit sequenced process.

Suggestions

Consolidate the 'Key patterns demonstrated' list and the Patterns section to remove redundancy and tighten conciseness.

Add a single explicit end-to-end proposal-writing workflow (gather context → draft problem statement → propose architecture → frame decisions → document risks → define scope) with checkpoints, so the sequence lives in one place.

Trim restated guidance in Anti-Patterns that merely rephrases the Tone Ceiling / specificity rules already given.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient and well-sectioned, but the 'Key patterns demonstrated' 10-item list and several anti-pattern entries restate material already covered in Patterns, and 'Tone Ceiling' repeats the specificity guidance — fitting 'mostly efficient but includes some unnecessary explanation or could be tightened' rather than the lean score-4 anchor.	3 / 5
Actionability	Concrete templates and worked examples (decision framing with the ink example, risk documentation with the SDK streaming risk) give mostly executable guidance for an instruction-only skill; minor gaps keep it just below the fully-copy-paste score-5 anchor.	4 / 5
Workflow Clarity	Sequenced guidance exists (the 10-step key-patterns list, the 4-step wave restructuring, numbered proposal sections) but the overall proposal-writing process is distributed across patterns rather than presented as one explicit ordered workflow with checkpoints — matching 'steps listed but validation gaps; checkpoints implicit.'	3 / 5
Progressive Disclosure	No bundle files exist, so the skill is appropriately self-contained with clear sections (Context, Patterns, Examples, Anti-Patterns); the only drag is overlap between the Examples and Anti-Patterns sections, fitting 'good structure; minor organization gaps' below the cleanly-split score-5 anchor.	4 / 5
	Total	14 / 20 Passed

Description

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

The description names a distinct domain and purpose but is hampered by the absence of an explicit 'Use when...' trigger clause and limited natural-language synonyms. Specificity is adequate but not comprehensive.

Suggestions

Add an explicit 'Use when...' clause naming concrete triggers (e.g., 'Use when proposing architecture changes, before implementation, or when product direction shifts invalidate existing assumptions').

Broaden trigger terms with natural synonyms users actually say — design docs, RFCs, ADRs, architecture decisions — not just 'architectural proposals'.

Enumerate a few concrete capabilities (e.g., 'structure proposals with problem statement, risks, and decision framing; restructure waves when foundations shift') to lift specificity toward the score-4/5 anchors.

Dimension	Reasoning	Score
Specificity	Names the domain ('architectural proposals') plus one-to-two actions ('write... proposals', 'drive alignment'), but the actions remain fairly abstract rather than a comprehensive list of concrete capabilities — matching the score-3 anchor and clearly below the multiple-specific-actions bar of score 4.	3 / 5
Completeness	It gives a clear 'what' (write proposals that drive alignment) but lacks any explicit 'when'/'Use when...' trigger clause, which per the judging guidelines caps completeness at 3.	3 / 5
Trigger Term Quality	It surfaces 'architectural proposals' and 'alignment' as relevant keywords, but omits the natural variations a user would actually say (design doc, RFC, ADR, architecture decision) — fitting 'some relevant keywords but missing common variations or synonyms.'	3 / 5
Distinctiveness Conflict Risk	'Architectural proposals' carves a distinct niche with low overlap risk against other skills, aligning with 'mostly distinct; minor overlap risk with closely related skills' and below the fully-distinct score-5 anchor.	4 / 5
	Total	13 / 20 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
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: bradygaster/squad
Path: .squad-templates/skills/architectural-proposals/SKILL.md
Commit: 9587fcd

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