quality-advisor
Purpose
Give proactive, in-the-moment quality guidance while an SDD artifact is being
written, so issues are caught during creation instead of at post-creation
validation. It scores section completion, detects documentation anti-patterns,
checks cumulative tagging, and validates naming — then returns actionable
recommendations.
When to Use
Use quality-advisor when:
- Authoring a new artifact and wanting live feedback.
- Reviewing an artifact before submission.
- Checking template-requirement, tag, or naming compliance for one document.
Do not use it for full bidirectional traceability or whole-project
validation (use ../doc-validator/SKILL.md), or non-SDD documentation.
Behavior
Given the artifact content, its type, and an optional check level (quick /
standard / strict), the skill:
- Loads template requirements for the artifact's layer from
${CLAUDE_PLUGIN_ROOT}/framework/registry/LAYER_REGISTRY.yaml — required sections, minimum tag
count, and special rules (e.g. PRD KPIs must be quantitative, EARS
WHEN-THE-SHALL syntax, SPEC YAML form). Code is the downstream execution
target of IPLAN, not a documentation artifact.
- Scores section completion — detects required sections, flags
missing/partial ones, and reports a completion score with specific issues.
- Detects anti-patterns — missing Document Control, placeholder text, vague
acceptance criteria, missing traceability tags, broken links, ID-format
violations, empty sections, orphan artifacts, count/cross-reference
mismatches, undefined acronyms, mixed ID notation, forward references to
non-existent documents — each with severity and a fix suggestion.
- Validates cumulative tagging — confirms the artifact carries exactly the
upstream tag families its layer requires (BRD 0 → … → IPLAN 7), with no gaps
and no downstream tags.
- Checks naming — document IDs
TYPE-NN, element IDs TYPE.NN.SS.xxxx,
threshold tags, and filename slugs, deferring to ../doc-naming/SKILL.md and
${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md; flags legacy patterns.
- Generates a quality report — overall status and score, error/warning/info
counts, per-area results, and prioritized recommendations plus next steps
(typically: fix errors, then run
../doc-validator/SKILL.md).
The framework ships no runtime code — this skill IS the checker, applying the
declarative checks above against the spec.
Related Resources
- Layer registry & tag rules:
${CLAUDE_PLUGIN_ROOT}/framework/registry/LAYER_REGISTRY.yaml
- ID & tag standards:
${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md
- Layer READMEs:
${CLAUDE_PLUGIN_ROOT}/framework/layers/02_PRD/README.md ·
${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/README.md
- Naming:
../doc-naming/SKILL.md
- Post-creation validation:
../doc-validator/SKILL.md · layer -audit skills
(e.g. ../doc-prd-audit/SKILL.md)
- Routing & next steps:
../doc-flow/SKILL.md
1---
2name: quality-advisor
3description: Provide real-time quality guidance during artifact creation - section completion, anti-pattern detection, cumulative-tag and naming checks - before an artifact is finished. Use while authoring or reviewing a single SDD document.
4metadata:
5 tags:
6 - sdd-workflow
7 - utility
8 - quality-assurance
9 custom_fields:
10 skill_category: utility
11 version: "0.25.0"
12 framework_spec_version: "0.51.0"
13 last_updated: "2026-05-23"
14---1516
17# quality-advisor
18
19## Purpose
20
21Give proactive, in-the-moment quality guidance while an SDD artifact is being
22written, so issues are caught during creation instead of at post-creation
23validation. It scores section completion, detects documentation anti-patterns,
24checks cumulative tagging, and validates naming — then returns actionable
25recommendations.
26
27## When to Use
28
29Use `quality-advisor` when:
30
31- Authoring a new artifact and wanting live feedback.
32- Reviewing an artifact before submission.
33- Checking template-requirement, tag, or naming compliance for one document.
34
35Do **not** use it for full bidirectional traceability or whole-project
36validation (use `../doc-validator/SKILL.md`), or non-SDD documentation.
37
38## Behavior
39
40Given the artifact content, its type, and an optional check level (quick /
41standard / strict), the skill:
42
431. **Loads template requirements** for the artifact's layer from
44 `${CLAUDE_PLUGIN_ROOT}/framework/registry/LAYER_REGISTRY.yaml` — required sections, minimum tag
45 count, and special rules (e.g. PRD KPIs must be quantitative, EARS
46 WHEN-THE-SHALL syntax, SPEC YAML form). Code is the downstream execution
47 target of IPLAN, not a documentation artifact.
482. **Scores section completion** — detects required sections, flags
49 missing/partial ones, and reports a completion score with specific issues.
503. **Detects anti-patterns** — missing Document Control, placeholder text, vague
51 acceptance criteria, missing traceability tags, broken links, ID-format
52 violations, empty sections, orphan artifacts, count/cross-reference
53 mismatches, undefined acronyms, mixed ID notation, forward references to
54 non-existent documents — each with severity and a fix suggestion.
554. **Validates cumulative tagging** — confirms the artifact carries exactly the
56 upstream tag families its layer requires (BRD 0 → … → IPLAN 7), with no gaps
57 and no downstream tags.
585. **Checks naming** — document IDs `TYPE-NN`, element IDs `TYPE.NN.SS.xxxx`,
59 threshold tags, and filename slugs, deferring to `../doc-naming/SKILL.md` and
60 `${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md`; flags legacy patterns.
616. **Generates a quality report** — overall status and score, error/warning/info
62 counts, per-area results, and prioritized recommendations plus next steps
63 (typically: fix errors, then run `../doc-validator/SKILL.md`).
64
65The framework ships no runtime code — this skill IS the checker, applying the
66declarative checks above against the spec.
67
68## Related Resources
69
70- Layer registry & tag rules: `${CLAUDE_PLUGIN_ROOT}/framework/registry/LAYER_REGISTRY.yaml`
71- ID & tag standards: `${CLAUDE_PLUGIN_ROOT}/framework/governance/ID_NAMING_STANDARDS.md`
72- Layer READMEs: `${CLAUDE_PLUGIN_ROOT}/framework/layers/02_PRD/README.md` ·
73 `${CLAUDE_PLUGIN_ROOT}/framework/layers/05_ADR/README.md`
74- Naming: `../doc-naming/SKILL.md`
75- Post-creation validation: `../doc-validator/SKILL.md` · layer `-audit` skills
76 (e.g. `../doc-prd-audit/SKILL.md`)
77- Routing & next steps: `../doc-flow/SKILL.md`
vladm3105