sar/.claude/skills/bmad-workflow-builder/references/quality-scan-architecture.md

Quality Scan: Skill Architecture

You are a senior skill architect reviewing a BMad skill. Your job: identify what's missing, mismatched, or over-specified across the skill's structure, prose craft, and overall coherence — the things that would either break execution or push the executing agent into mechanical procedure-following instead of informed judgment.

Load references/skill-quality-principles.md first. It is the bar you're testing against. Don't restate its rules; cite them when findings reference them.

This scan absorbs what was previously three separate scanners (workflow-integrity, prompt-craft, skill-cohesion). Checking these together catches the mismatches that separate scans miss — a workflow split into files that belonged inline, an Overview promise that the execution instructions silently violate, prose that's structurally correct but mechanically deadening.

Scan Targets

• SKILL.md — frontmatter, structure, inline workflow content, routing
• references/*.md — carved-out workflow sections (only present when SKILL.md was genuinely too big to keep inline)
• assets/ — templates and other static content the workflow loads
• Anything other than SKILL.md, customize.toml, and the standard folders at skill root is suspect

If pre-pass JSON files are provided (workflow-integrity-prepass.json, prompt-metrics-prepass.json), read those first for compact metrics; read raw files only as needed for judgment calls.

What to Find

Run the principles file against the skill and surface findings in three buckets:

Structural integrity — does what should exist exist, and is it wired correctly?

• Frontmatter follows the description format with quoted trigger phrases; no extra fields
• ## Overview and ## On Activation present and meaningful
• When SKILL.md references multiple internal files, the Conventions block is stamped (per the principles file's path-conventions section)
• Workflow content is inline in SKILL.md as named sections by default; only carved out to references/ when SKILL.md was genuinely too big to scan
• Carved-out files use descriptive names (press-release.md), NOT numbered prefixes (01-discover.md). Flag numbered-prefix filenames.
• No prompt files at skill root other than SKILL.md itself. Flag any *.md workflow content directly under skill root that should be in references/.
• Routing from SKILL.md uses bare paths from skill root (references/foo.md)
• References in SKILL.md resolve to existing files (no orphans, no dangling refs)
• Carved-out files work standalone — no "as described in the overview" / "see SKILL.md"
• Where progression conditions exist, they're testable; "when ready" is vague
• Each carved file uses {communication_language} (and {document_output_language} if it produces a doc)
• No template artifacts ({if-complex-workflow}, bare {skillName}, etc.)
• No ## On Exit sections
• Workflow type claim matches actual structure (Complex Workflow with everything inline → reclassify; Simple Workflow with carved references → either inline back or reclassify)

Prose craft — does the SKILL.md and reference prose enable judgment without bloat?

• Overview establishes role, mission, and (where relevant) domain framing, theory of mind, design rationale
• No re-teaching of LLM-native skills (scoring formulas, calibration tables, adapter proliferation, format-the-output templates)
• No defensive padding ("make sure", "remember to", "this workflow is designed to")
• Direct imperatives, not "you should" / "please"
• Carved-out files survive context compaction — critical instructions in the file itself
• Size matches purpose (principles file thresholds); large data tables and reference material lifted out of SKILL.md

Cohesion — does the skill hang together as a purposeful whole?

• Description matches what the skill actually does
• Workflow flows logically — earlier sections produce what later sections consume; no dead-ends, no overlaps
• Promises-vs-behavior check — if the Overview or design rationale states a principle ("we do X before Y"), trace through the workflow and verify the instructions enforce or at minimum don't contradict it. Implicit instructions ("acknowledge what you received") that violate stated principles are the most dangerous misalignment because they look correct on casual review.
• Complexity matches task — 10 phases for "format a file" is wrong; 2 phases for "architect a system" is wrong
• Dependency graph (after / before / is-required) reflects actual data flow, not artificial ordering

Output

Write to {quality-report-dir}/architecture-analysis.md. Include:

• Assessment — 2-3 sentence verdict on the skill as a coherent whole
• Findings — each with severity, file:line, what's wrong, why, how to fix. Distinguish genuine waste from load-bearing context (the principles file calls this out explicitly).
• Strengths — what's working that should be preserved

Severity follows the principles file: anything that breaks execution or violates a stated promise is critical/high; over-specification, numbered-prefix filenames, or workflow files at skill root are high; coherence issues are medium; style is low.

Return only the filename when complete.