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