Skills
▥NYC
skills/vladm3105/aidoc-flow-framework/quality-advisor

quality-advisor

SKILL.md

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

Input Type Required Description
artifact_content string Yes Current content of artifact being created
artifact_type string Yes Type of artifact (BRD, PRD, SPEC, etc.)
artifact_id string No Document ID if assigned (e.g., PRD-00)
check_level string No Level of checks: "quick", "standard" (default), "strict"

Skill Workflow

Step 1: Identify Template Requirements

Load requirements for the specified artifact type:

Template Requirements by Type (per LAYER_REGISTRY v1.6):

Layer Artifact Required Sections Min Tags Special Requirements
1 BRD Document Control, Purpose, Stakeholders, Objectives, Requirements, Traceability 0 None
2 PRD Document Control, Problem, Goals, Non-Goals, User Needs, Features, KPIs, Traceability 1 (@brd) KPIs must be quantitative
3 EARS Document Control, Requirements (WHEN-THE-SHALL), Traceability 2 (@brd, @prd) EARS syntax validation
4 BDD Feature, Scenarios, Tags 3 (@brd, @prd, @ears) Gherkin syntax
5 ADR Document Control, Context, Decision, Rationale, Consequences, Traceability 4 (@brd, @prd, @ears, @bdd) Decision must be explicit
6 SYS Document Control, System Requirements, Traceability 5 Technical specifications
7 REQ Document Control, Requirement, Acceptance Criteria, Traceability 6 Atomic requirement
8 CTR Document Control, Interfaces, Data Models, Contract Clauses, Traceability 7 Dual-file format (md+yaml)
9 SPEC id, description, methods, traceability 7 YAML format
10 TSPEC Document Control, Test Cases, Coverage, Traceability 8 UTEST/ITEST/STEST/FTEST types
11 TASKS Document Control, Tasks, Dependencies, Traceability 9 Actionable TODOs

Note: Layers 12-14 (CODE, TESTS, VALIDATION) are execution layers, not documentation artifacts.

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:

ID Name Description Severity Detection
AP-001 Missing Document Control No version/status metadata Error Section not found
AP-002 Placeholder Text [TBD], TODO, XXX in content Warning Regex match
AP-003 Vague Acceptance Criteria No measurable outcomes Warning Missing numbers/percentages
AP-004 Missing Traceability Tags Required upstream tags absent Error Tag count check
AP-005 Broken Internal Links [ID](path) links with invalid paths Error Link validation
AP-006 ID Format Violation Non-standard document ID Error Regex match
AP-007 Empty Required Section Section header present but no content Warning Content length check
AP-008 Orphan Artifact No upstream references Warning Traceability check
AP-009 Missing Anchor Document lacks primary anchor ID Warning Anchor detection
AP-010 Duplicate ID Reference Same ID referenced multiple times Info Duplicate check
AP-011 Section Count Mismatch total_sections metadata differs from actual section files Error SEC-E001 validation
AP-012 Cross-Reference Title Mismatch Link text differs from target section heading Error XREF-E001/E002 validation
AP-013 Mixed ID Notation Document uses both hyphen (TYPE-NN) and dot (TYPE.NN) formats Error IDPAT-E003 validation
AP-014 Diagram-Text Inconsistency Mermaid diagram components don't match prose claims Warning DIAG-E001/W001 validation
AP-015 Undefined Acronym Acronym used without first-use definition Error TERM-E002 validation
AP-016 Count Mismatch Stated count (e.g., "18 requirements") differs from itemized total Error COUNT-E001 validation
AP-017 Forward Reference to Non-Existent Document Upstream doc references specific downstream IDs (e.g., PRD→ADR-01) Error FWDREF-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 (per LAYER_REGISTRY v1.6):

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
  CTR:
    layer: 8
    required_tags: [@brd, @prd, @ears, @bdd, @adr, @sys, @req]
    tag_count: 7
  SPEC:
    layer: 9
    required_tags: [@brd, @prd, @ears, @bdd, @adr, @sys, @req]
    optional_tags: [@ctr]
    tag_count: 7
  TSPEC:
    layer: 10
    required_tags: [@brd, @prd, @ears, @bdd, @adr, @sys, @req, @spec]
    optional_tags: [@ctr]
    tag_count: 8
  TASKS:
    layer: 11
    required_tags: [@brd, @prd, @ears, @bdd, @adr, @sys, @req, @spec, @tspec]
    optional_tags: [@ctr]
    tag_count: 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, element ID, and filename conventions per doc-naming skill.

Naming Rules (see doc-naming skill for complete standards):

naming_conventions:
  # Document ID format
  document_id_format: "{TYPE}-{NN}"  # e.g., PRD-01
  filename_format: "{TYPE}-{NN}_{slug}.md"  # e.g., PRD-01_authentication.md

  # Element ID format (unified)
  element_id_format: "{TYPE}.{NN}.{TT}.{SS}"  # e.g., PRD.01.09.01

  # Threshold tag format
  threshold_format: "@threshold: {TYPE}.{NN}.{key}"  # e.g., @threshold: PRD.01.perf.auth.p99

  slug_rules:
    - lowercase
    - underscores for spaces
    - no special characters
    - descriptive of content

Naming Validation Output:

naming_validation:
  document_id: PRD-01
  id_format_valid: true
  filename: "PRD-01_authentication.md"
  filename_valid: true
  element_ids:
    total: 24
    valid: 22
    invalid: 2
    issues:
      - "PRD.01.25.01 - code 25 not valid for PRD"
      - "US-001 - deprecated pattern, use PRD.01.09.SS"
  threshold_tags:
    total: 8
    valid: 7
    invalid: 1
    issues:
      - "perf.auth.p99 - missing TYPE.NN prefix"
  legacy_patterns_detected: 1

Reference: See doc-naming skill for complete element type codes and validation rules.

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

Integration Description
doc-naming Element ID format, threshold tags, legacy pattern detection
doc-*-autopilot Invoked during Phase 3 (artifact generation) for real-time guidance
doc-*-validator Structural validation (use quality-advisor for creation, validator for post-creation)
doc-*-reviewer Content review (use quality-advisor for creation, reviewer for final QA)
trace-check Shares validation logic for traceability checks
context-analyzer Uses project context for reference validation

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

Metric Target
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

Source Type Reference
PRD-00 Product Requirements PRD-00
ADR-000 Architecture Decision ADR-000

Downstream Artifacts

Artifact Type Reference
doc-* skills Skill Consumer Quality checks during creation

Version History

Version Date Changes
1.1.0 2026-02-08 Updated layer assignments per LAYER_REGISTRY v1.6; Added CTR (L8), TSPEC (L10); Fixed SPEC to L9, TASKS to L11; Integrated doc-naming skill for element ID validation
1.0.0 2025-11-29 Initial release

Status: Active Author: AI Dev Flow Framework Team

Weekly Installs
18
Repository
vladm3105/aidoc-flow-framework
First Seen
Jan 24, 2026
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykPass
Installed on
gemini-cli13
claude-code12
codex12
antigravity11
opencode11
windsurf10