quality-advisor

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.

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

| 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" |

Step 1: Identify Template Requirements

Load requirements for the specified artifact type:

Template Requirements by Type:

| Artifact | Required Sections | Minimum Tags | Special Requirements |

|----------|-------------------|--------------|----------------------|

| BRD | Document Control, Purpose, Stakeholders, Objectives, Requirements, Traceability | 0 | None |

| PRD | Document Control, Problem, Goals, Non-Goals, User Needs, Features, KPIs, Traceability | 1 (@brd) | KPIs must be quantitative |

| EARS | Document Control, Requirements (WHEN-THE-SHALL), Traceability | 2 (@brd, @prd) | EARS syntax validation |

| BDD | Feature, Scenarios, Tags | 3 (@brd, @prd, @ears) | Gherkin syntax |

| ADR | Document Control, Context, Decision, Rationale, Consequences, Traceability | 4 | Decision must be explicit |

| SYS | Document Control, System Requirements, Traceability | 5 | Technical specifications |

| REQ | Document Control, Requirement, Acceptance Criteria, Traceability | 6 | Atomic requirement |

| SPEC | id, description, methods, traceability | 7-9 | YAML format |

| TASKS | Document Control, Tasks, Dependencies, Traceability | 8-10 | Actionable TODOs |

Step 2: Check Section Completion

Verify all required sections are present and populated:

Section Detection:

```python

# 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:

```yaml

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:

```yaml

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:

```yaml

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:

```yaml

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:

```yaml

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:

```yaml

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:

```yaml

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 1: Mid-Creation Check

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

Quality Feedback:

```yaml

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:

```yaml

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:

```yaml

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 | Description |

|-------------|-------------|

| doc-* skills | Invoked during artifact creation for real-time guidance |

| trace-check | Shares validation logic for traceability checks |

| context-analyzer | Uses project context for reference validation |

| doc-validator | Overlaps with quality checks (use quality-advisor for creation, doc-validator for batch) |

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% |

Required Tags:

```

@prd: PRD.000.003

@adr: ADR-000

```

Upstream Sources

| Source | Type | Reference |

|--------|------|-----------|

| PRD-00 | Product Requirements | [PRD-00]({project_root}/ai_dev_flow/PRD/PRD-00_ai_assisted_documentation_features.md#PRD-00) |

| ADR-000 | Architecture Decision | [ADR-000]({project_root}/ai_dev_flow/ADR/ADR-00_ai_powered_documentation_assistant_architecture.md#ADR-000) |

Downstream Artifacts

| Artifact | Type | Reference |

|----------|------|-----------|

| doc-* skills | Skill Consumer | Quality checks during creation |

---

Version: 1.0.0

Created: 2025-11-29

Status: Active

Author: AI Dev Flow Framework Team