Skip to content
quality-advisor logo

Quality Advisor

quality-advisor

Proactive quality guidance system that monitors artifact creation and provides real-time feedback on documentation quality

mattnigh/skills_collection0installs24stars

SKILL.md

Full skill instructions

quality-advisor

Purpose

Provide proactive quality guidance during artifact creation by monitoring section completion, detecting anti-patterns, and validating compliance with SDD standards.

Problem Solved: Documentation quality varies based on user expertise. Issues are typically found after artifact creation during validation, causing rework.

Solution: Real-time quality monitoring that identifies issues during creation, suggests improvements, and validates compliance before the artifact is complete.

When to Use This Skill

Use quality-advisor when:

  • Creating a new documentation artifact
  • Reviewing an artifact before submission
  • Want to check compliance with template requirements
  • Need guidance on common mistakes to avoid
  • Validating cumulative tagging compliance

Do NOT use when:

  • Full traceability validation needed (use trace-check)
  • Validating entire project (use doc-validator)
  • Non-SDD documentation

Skill Inputs

InputTypeRequiredDescription
artifact_contentstringYesCurrent content of artifact being created
artifact_typestringYesType of artifact (BRD, PRD, SPEC, etc.)
artifact_idstringNoDocument ID if assigned (e.g., PRD-00)
check_levelstringNoLevel of checks: "quick", "standard" (default), "strict"

Skill Workflow

Step 1: Identify Template Requirements

Load requirements for the specified artifact type:

Template Requirements by Type:

ArtifactRequired SectionsMinimum TagsSpecial Requirements
BRDDocument Control, Purpose, Stakeholders, Objectives, Requirements, Traceability0None
PRDDocument Control, Problem, Goals, Non-Goals, User Needs, Features, KPIs, Traceability1 (@brd)KPIs must be quantitative
EARSDocument Control, Requirements (WHEN-THE-SHALL), Traceability2 (@brd, @prd)EARS syntax validation
BDDFeature, Scenarios, Tags3 (@brd, @prd, @ears)Gherkin syntax
ADRDocument Control, Context, Decision, Rationale, Consequences, Traceability4Decision must be explicit
SYSDocument Control, System Requirements, Traceability5Technical specifications
REQDocument Control, Requirement, Acceptance Criteria, Traceability6Atomic requirement
SPECid, description, methods, traceability7-9YAML format
TASKSDocument Control, Tasks, Dependencies, Traceability8-10Actionable TODOs

Step 2: Check Section Completion

Verify all required sections are present and populated:

Section Detection:

# Section patterns by type
SECTION_PATTERNS = {
    "document_control": r"## Document Control",
    "problem_statement": r"## \d+\. Problem",
    "goals": r"## \d+\. Goals",
    "non_goals": r"## \d+\. Non-Goals",
    "traceability": r"## \d+\. Traceability|## 7\. Traceability",
    "kpis": r"## \d+\. KPIs|## KPIs",
    "acceptance_criteria": r"### Acceptance Criteria|## Acceptance",
}

Completion Scoring:

section_completion:
  document_control:
    present: true
    complete: true
    score: 100%
  problem_statement:
    present: true
    complete: true
    score: 100%
  goals:
    present: true
    complete: partial
    score: 60%
    issues:
      - "Goal G-003 missing success metric"
      - "Goals not prioritized (P0, P1, P2)"
  kpis:
    present: true
    complete: false
    score: 30%
    issues:
      - "KPI 'user adoption' lacks quantitative target"
      - "No performance metrics defined"
  traceability:
    present: true
    complete: partial
    score: 70%
    issues:
      - "Missing @brd tag (required for Layer 2)"
      - "Downstream artifacts section empty"
  overall_score: 72%

Step 3: Detect Anti-Patterns

Identify common documentation mistakes:

Anti-Pattern Catalog:

IDNameDescriptionSeverityDetection
AP-001Missing Document ControlNo version/​status metadataErrorSection not found
AP-002Placeholder Text[TBD], TODO, XXX in contentWarningRegex match
AP-003Vague Acceptance CriteriaNo measurable outcomesWarningMissing numbers/​percentages
AP-004Missing Traceability TagsRequired upstream tags absentErrorTag count check
AP-005Broken Internal Links[ID](path) links with invalid pathsErrorLink validation
AP-006ID Format ViolationNon-standard document IDErrorRegex match
AP-007Empty Required SectionSection header present but no contentWarningContent length check
AP-008Orphan ArtifactNo upstream referencesWarningTraceability check
AP-009Missing AnchorDocument lacks primary anchor IDWarningAnchor detection
AP-010Duplicate ID ReferenceSame ID referenced multiple timesInfoDuplicate check
AP-011Section Count Mismatchtotal_sections metadata differs from actual section filesErrorSEC-E001 validation
AP-012Cross-Reference Title MismatchLink text differs from target section headingErrorXREF-E001/​E002 validation
AP-013Mixed ID NotationDocument uses both hyphen (TYPE-NN) and dot (TYPE.NN) formatsErrorIDPAT-E003 validation
AP-014Diagram-Text InconsistencyMermaid diagram components don't match prose claimsWarningDIAG-E001/​W001 validation
AP-015Undefined AcronymAcronym used without first-use definitionErrorTERM-E002 validation
AP-016Count MismatchStated count (e.g., "18 requirements") differs from itemized totalErrorCOUNT-E001 validation
AP-017Forward Reference to Non-Existent DocumentUpstream doc references specific downstream IDs (e.g., PRD→ADR-01)ErrorFWDREF-E001 validation

Anti-Pattern Detection Output:

anti_patterns_detected:
  - id: AP-004
    name: Missing Traceability Tags
    severity: error
    location: "Section 7: Traceability"
    details: "PRD requires @brd tag (Layer 2 cumulative requirement)"
    suggestion: "Add '@brd: BRD.NN.EE.SS' to Traceability section"

  - id: AP-003
    name: Vague Acceptance Criteria
    severity: warning
    location: "Section 6: KPIs"
    details: "KPI 'improve user experience' has no measurable target"
    suggestion: "Add quantitative metric: 'User satisfaction ≥4.0/​5.0'"

  - id: AP-002
    name: Placeholder Text
    severity: warning
    location: "Section 4: User Needs, line 45"
    details: "Found placeholder '[TBD]'"
    suggestion: "Replace with actual user need or remove section"

Step 4: Validate Cumulative Tagging

Check tag hierarchy compliance:

Tag Hierarchy by Layer:

cumulative_tag_requirements:
  BRD:
    layer: 1
    required_tags: []
    tag_count: 0
  PRD:
    layer: 2
    required_tags: [@brd]
    tag_count: 1
  EARS:
    layer: 3
    required_tags: [@brd, @prd]
    tag_count: 2
  BDD:
    layer: 4
    required_tags: [@brd, @prd, @ears]
    tag_count: 3
  ADR:
    layer: 5
    required_tags: [@brd, @prd, @ears, @bdd]
    tag_count: 4
  SYS:
    layer: 6
    required_tags: [@brd, @prd, @ears, @bdd, @adr]
    tag_count: 5
  REQ:
    layer: 7
    required_tags: [@brd, @prd, @ears, @bdd, @adr, @sys]
    tag_count: 6
  SPEC:
    layer: 10
    required_tags: [@brd, @prd, @ears, @bdd, @adr, @sys, @req]
    optional_tags: [@impl, @ctr]
    tag_count: 7-9

Tag Validation Output:

tag_validation:
  artifact_type: PRD
  layer: 2
  required_tags: ["@brd"]
  found_tags: []
  missing_tags: ["@brd"]
  status: fail
  message: "Layer 2 artifact requires @brd tag"
  fix_suggestion: |
    Add to Traceability section:
    ```
    @brd: BRD.001.003
    ```

Step 5: Check Naming Conventions

Validate document ID and filename conventions:

Naming Rules:

naming_conventions:
  id_format: "{TYPE}-{NNN}"  # e.g., PRD-00
  filename_format: "{TYPE}-{NNN}_{slug}.md"  # e.g., PRD-00_authentication.md
  slug_rules:
    - lowercase
    - underscores for spaces
    - no special characters
    - descriptive of content
  h1_format: "# {TYPE}-{NNN}: {Title}"

Naming Validation Output:

naming_validation:
  document_id: PRD-00
  id_format_valid: true
  filename: "PRD-00_ai_features.md"
  filename_valid: true
  h1_header: "# PRD-00: AI-Assisted Documentation Features"
  h1_valid: true
  anchor_present: true
  anchor_id: "PRD-00"
  issues: []

Step 6: Generate Quality Report

Assemble comprehensive quality assessment:

Quality Report Format:

quality_report:
  artifact_id: PRD-00
  artifact_type: PRD
  check_timestamp: 2025-11-29T14:30:00Z
  check_level: standard

  overall_status: warning
  quality_score: 72%

  summary:
    errors: 1
    warnings: 3
    info: 1
    passed_checks: 12

  section_completion:
    complete: 5
    partial: 2
    missing: 0
    score: 85%

  anti_patterns:
    - severity: error
      count: 1
      details: "Missing @brd tag"
    - severity: warning
      count: 3
      details: "Vague KPIs, placeholder text, incomplete goals"

  tag_compliance:
    status: fail
    required: 1
    found: 0
    missing: ["@brd"]

  naming_compliance:
    status: pass
    all_checks_passed: true

  recommendations:
    high_priority:
      - "Add @brd tag to Traceability section (required for Layer 2)"
    medium_priority:
      - "Add quantitative targets to KPIs"
      - "Remove [TBD] placeholder from User Needs section"
      - "Prioritize goals with P0, P1, P2 labels"
    low_priority:
      - "Consider adding more downstream artifact references"

  next_steps:
    - "Fix error-level issues before submission"
    - "Address warnings for quality improvement"
    - "Run trace-check after completion for full validation"

Example Usage

Example 1: Mid-Creation Check

User Request: "Check quality of my PRD in progress"

Quality Feedback:

quality_status: in_progress
current_score: 65%
blocking_issues:
  - "Missing Document Control section at top"
  - "No traceability section found"
improvement_suggestions:
  - "Add Document Control table before Section 1"
  - "Create Section 7: Traceability with @brd tag"
  - "Add measurable KPIs (currently vague)"
completion_estimate: "3 sections need attention"

Example 2: Pre-Submission Review

User Request: "Is this SPEC ready for submission?"

Quality Assessment:

submission_readiness: not_ready
blocking_issues:
  - severity: error
    issue: "Missing @req tag (required for Layer 10)"
  - severity: error
    issue: "YAML syntax error at line 45"
warnings:
  - "verification section references non-existent BDD-015"
  - "id field uses camelCase instead of snake_case"
recommendation: "Fix 2 errors before submission"

Example 3: Quick Compliance Check

User Request: "Quick check on tag compliance for this REQ"

Tag Check Output:

artifact_type: REQ
layer: 7
tag_compliance: pass
required_tags:
  - "@brd: BRD.01.01.01 ✓"
  - "@prd: PRD.01.07.01 ✓"
  - "@ears: EARS.01.24.01 ✓"
  - "@bdd: BDD.01.13.01 ✓"
  - "@adr: ADR-02 ✓"
  - "@sys: SYS.01.25.01 ✓"
tag_count: "6/​6 required tags present"
status: "Ready for downstream artifacts"

Integration with Other Skills

IntegrationDescription
doc-* skillsInvoked during artifact creation for real-time guidance
trace-checkShares validation logic for traceability checks
context-analyzerUses project context for reference validation
doc-validatorOverlaps with quality checks (use quality-advisor for creation, doc-validator for batch)

Quality Gates

Definition of Done

  • All required sections identified
  • Section completion scored
  • Anti-patterns detected and reported
  • Cumulative tagging validated
  • Naming conventions checked
  • Quality report generated
  • Actionable recommendations provided

Performance Targets

MetricTarget
Quick check latency<100ms
Standard check latency<500ms
Strict check latency<1s
False positive rate<5%

Traceability

Required Tags:

@prd: PRD.000.003
@adr: ADR-000

Upstream Sources

SourceTypeReference
PRD-00Product RequirementsPRD-00
ADR-000Architecture DecisionADR-000

Downstream Artifacts

ArtifactTypeReference
doc-* skillsSkill ConsumerQuality checks during creation

Version Information

Version: 1.0.0 Created: 2025-11-29 Status: Active Author: AI Dev Flow Framework Team

More skills from mattnigh

spring-framework-patterns logo
mattnigh/skills_collection

spring-framework-patterns

Comprehensive Spring Framework and Spring Boot best practices including dependency injection patterns, bean lifecycle and scopes, REST API development, Spring Data JPA, service layer design, Spring Security, testing strategies, caching, AOP, async processing, error handling, and common anti-patte...

24 0
View

TypeScript厳格モードによる型安全性設計を専門とするスキル。 📖 参照書籍: - 『Effective TypeScript』(Dan Vanderkam): 型設計 📚 リソース参照: - `resources/Level1_basics.md`: レベル1の基礎ガイド - `resources/Level2_intermediate.md`: レベル2の実務ガイド - `resources/Level3_advanced.md`: レベル3の応用ガイド - `resources/Level4_expert.md`: レベル4の専門ガイド - `resources/di...

24 0
View
deploying-cloud-k8s logo
mattnigh/skills_collection

deploying-cloud-k8s

Deploys applications to cloud Kubernetes (AKS/GKE/DOKS) with CI/CD pipelines. Use when deploying to production, setting up GitHub Actions, troubleshooting deployments. Covers build-time vs runtime vars, architecture matching, and battle-tested debugging.

24 0
View
moai-alfred-agent-guide logo
mattnigh/skills_collection

moai-alfred-agent-guide

19-agent team structure, decision trees for agent selection, Haiku vs Sonnet model selection, and agent collaboration principles. Use when deciding which sub-agent to invoke, understanding team responsibilities, or learning multi-agent orchestration.

24 0
View
mermaid-diagram-generator logo
mattnigh/skills_collection

mermaid-diagram-generator

Converts architecture descriptions, module specs, or workflow docs into Mermaid diagrams. Use when visualizing brick module relationships, workflows (DDD, investigation), or system architecture. Supports: flowcharts, sequence diagrams, class diagrams, state machines, entity relationship diagrams,...

24 0
View
pre-flight-check logo
mattnigh/skills_collection

pre-flight-check

INVOKE FIRST before any code work. Validates git workflow (branch, issue, worklog) and checks approach. Use at START of every task and END before completing. Prevents skipped steps.

24 0
View
browser-dev-tools logo
mattnigh/skills_collection

browser-dev-tools

This skill should be used when working with browser-rendered artifacts (i.e. Bun, React/React Native) to proactively validate that development work on localhost is being built appropriately and to support debugging browser-rendered content. Use this skill after making frontend changes to verify t...

24 0
View
lead-dev logo
mattnigh/skills_collection

lead-dev

Lead Développeur - Coordination technique opérationnelle, code review, mentoring et livraison. Pair de web-dev-process au niveau OPÉRATIONS.

24 0
View
worker-monitor logo
mattnigh/skills_collection

worker-monitor

Monitor Docker workers, RQ queue health, and auto-scale workers (max 4). Use when: checking job progress, monitoring queue depth, scaling workers up/down, diagnosing slow processing, or waiting for jobs to complete. Referenced by data-quality skill during reprocessing.

24 0
View
bump-version logo
mattnigh/skills_collection

bump-version

This skill should be used when the user wants to bump the version number in the workspace. It updates versions across all pyproject.toml files (root, tde, and tda packages) and the CHANGELOG.md to keep them synchronized.

24 0
View
check-code-quality logo
mattnigh/skills_collection

check-code-quality

Run comprehensive Rust code quality checks including compilation, linting, documentation, and tests. Use after completing code changes and before creating commits.

24 0
View

Popular AI tools

Kaiber logo
Video

Kaiber

Generate, edit, and beat-sync AI video with leading models in one workspace.

Paid
View
Vimcal logo
Productivity

Vimcal

The world's fastest calendar for remote work

Free
View

Transform Your Design with AI Designer by ImgCreator.ai

Freemium
View
Akool AI logo
Content & writing

Akool AI

Revolutionizing Video Production with AI-Powered Creativity

Paid
View

Extend an image past the frame and let AI fill the new aspect ratio.

Freemium
View
StarByFace logo
Security

StarByFace

Discover your celebrity doppelgänger with StarByFace!

Free
View
C

ChainClarity explains 700+ crypto whitepapers in plain English, with layered summaries, comparisons, research tools, alerts, and a $4.99 Pro plan.

Freemium
View
Opus Clip logo
Coding & apps

Opus Clip

Opus.ai: Revolutionize Your Web Experience

Free
View