bi-agents/_bmad/wds/workflows/4-ux-design/templates/diagnostic-report-template.md

Diagnostic Report Template

Use this template for generating diagnostic reports during page specification validation.

---

Step-Specific Diagnostic Report

🔍 [Step Name] Audit

**Status:** ✅ PASS / ⚠️ WARNING / ❌ CRITICAL

**Issues Found:**
1. [Issue type] [Description]
   - Location: Line X-Y
   - Current: [what exists now]
   - Should be: [what it should be]
   - Why: [explanation of why this matters]

2. [Issue type] [Description]
   - Location: Line X-Y
   - Current: [what exists now]
   - Should be: [what it should be]
   - Why: [explanation of why this matters]

**Recommendation:**
[Specific actionable fix with examples]

**Example of Correct Format:**
```[language]
[code example showing correct implementation]

Would you like me to fix this?

---

## Validation Checklist Format

```yaml
[section_name]_validated:
  field_1: [true/false]
  field_2: [true/false]
  field_3: [true/false]
  status: [pass/warning/critical]

---

Issue Severity Levels

✅ PASS

• All checks passed
• No issues found
• Specification meets standards

⚠️ WARNING

• Non-critical issues found
• Specification functional but could be improved
• Recommended fixes, not required

❌ CRITICAL

• Critical issues that must be fixed
• Missing required sections
• Specification incomplete or non-compliant
• Blocks developer handoff

---

Common Issue Types

Missing Section

❌ Missing required section: [Section Name]
   - Location: Should appear after [Previous Section]
   - Why: [Explanation of why this section is required]
   - Example: [Show what the section should look like]

Incorrect Format

⚠️ Incorrect format: [Element Name]
   - Location: Line X
   - Current: [what's there now]
   - Should be: [correct format]
   - Why: [Explanation of why format matters]

Missing Object ID

❌ Missing Object ID: [Component Name]
   - Location: Line X
   - Current: Component has no OBJECT ID declaration
   - Should be: **OBJECT ID**: `component-name`
   - Why: Object IDs enable traceability from spec → code → Figma

Design System Violation

❌ Design System violation: CSS details in page spec
   - Location: Line X-Y
   - Current: Contains hex codes, pixel values, CSS classes
   - Should be: Component references with Design System links
   - Why: Page specs focus on WHAT/WHY, Design System handles HOW

Incomplete Coverage

⚠️ Incomplete Object Registry coverage
   - Missing: [list of Object IDs not in registry]
   - Orphaned: [list of Object IDs in registry but not in sections]
   - Coverage: X% (should be 100%)
   - Why: Registry must be single source of truth for all elements

---

Recommendation Format

Simple Fix

**Recommendation:**
Add the missing section after [Previous Section]:

```markdown
## [Section Name]

[Content template]

Would you like me to add this section?

### Complex Fix
```markdown
**Recommendation:**
1. Extract CSS details to Design System documentation
2. Replace inline styles with component references
3. Add Design System links for colors/typography
4. Keep page-specific layout notes (mobile vs desktop behavior)

**Next Steps:**
- Move color values to `Design-System/Foundation/Colors/`
- Move typography to `Design-System/Foundation/Typography/`
- Update page spec to reference Design System components

Would you like me to help extract these styles to the Design System?

---

Final Validation Report Format

# Page Specification Quality Report

**Page:** [Page Number] [Page Name]
**Audit Date:** [Date]
**Overall Status:** ✅ PASS / ⚠️ NEEDS WORK / ❌ CRITICAL ISSUES

## Executive Summary
[Brief overview of specification quality]

## Critical Issues (Must Fix Before Handoff)
[List critical issues from all steps]

## Warnings (Should Fix)
[List warnings from all steps]

## Info (Nice to Have)
[List informational items]

## Coverage Metrics
- Object Registry Coverage: X%
- Sketch Coverage: X%
- Design System References: X%
- Platform Metadata: Complete/Incomplete

## Recommendations
[Prioritized list of fixes]

## Next Steps
[What to do next based on findings]

---

Usage Guidelines

1. Be Specific: Always include line numbers and exact examples
2. Be Helpful: Explain WHY each issue matters
3. Be Actionable: Provide clear recommendations with examples
4. Be Conversational: Use friendly, collaborative tone
5. Be Respectful: Let designer decide whether to implement fixes
6. Be Thorough: Don't skip issues, but group related problems

---

Example Complete Report

🔍 Page Metadata Audit

**Status:** ⚠️ WARNING

**Issues Found:**
1. ⚠️ Missing scenario inheritance reference (Line 17-23)
   - Location: Page Metadata section
   - Current: All platform fields present but no inheritance link
   - Should be: "**Inherits From:** Scenario 03 Platform Strategy"
   - Why: Creates explicit traceability from Product Brief → Scenario → Page

**Recommendation:**
Add inheritance reference after Navigation Context:

```markdown
**Navigation Context**: Authenticated - overlays calendar page

**Inherits From**: Scenario 03 Platform Strategy (see scenario overview)

This creates explicit traceability chain and ensures platform context is properly inherited.

Would you like me to add this reference?