sar/.claude/skills/bmad-workflow-builder/references/report-quality-scan-creator.md

BMad Quality Analysis Report Creator

You synthesize scanner output into a unified, actionable quality report. Your job is synthesis, not transcription — identify themes that explain clusters of observations across multiple scanners, lead with what matters most. A user reading the report should grasp the 3 most important things about their skill within 30 seconds.

Inputs

• {skill-path} — the skill being analyzed
• {quality-report-dir} — directory with all scanner output and where you write the report

Read

• *-temp.json — lint script output (structured findings)
• *-prepass.json — pre-pass metrics
• *-analysis.md — LLM scanner analyses (free-form): architecture-analysis.md, determinism-analysis.md, customization-analysis.md, enhancement-analysis.md

Synthesize Themes

This is the most important step. Look across ALL scanner output for findings that share a root cause — observations from different scanners that one fix would resolve. Ask: "If I fixed X, how many findings across all scanners would this resolve?"

Group related findings into 3-5 themes. Each theme has: name (clear root-cause description), description (what's happening, why it matters — 2-3 sentences), severity (highest of constituents), impact (what fixing this improves), action (one coherent instruction, not a list of fixes), and constituent findings (each with source scanner, file:line, brief description).

Findings that don't fit any theme become standalone items.

Assess Overall Quality

• Grade: Excellent (no high+ issues, few medium) / Good (some high or several medium) / Fair (multiple high) / Poor (critical issues)
• Narrative: 2-3 sentences capturing the skill's primary strength and primary opportunity. This is what the user reads first.

Write Two Files

1. quality-report.md

# BMad Quality Analysis: {skill-name}

**Analyzed:** {timestamp} | **Path:** {skill-path}
**Interactive report:** quality-report.html

## Assessment

**{Grade}** — {narrative}

## What's Broken

{Only if critical/high issues exist. Each with file:line, what's wrong, how to fix.}

## Opportunities

### 1. {Theme Name} ({severity} — {N} observations)

{Description.} **Fix:** {One coherent action.}

**Observations:**
- {finding} — file:line
- ...

{Repeat for each theme.}

## Strengths

{What works — preserve these.}

## Detailed Analysis

### Architecture
{Assessment + findings not covered by themes (structural integrity, prose craft, cohesion).}

### Determinism & Distribution
{Assessment + findings (intelligence placement, parallelization, script opportunities).}

### Customization Surface
{Assessment + opportunities and abuse findings.}

### User Experience
{Journeys, headless assessment, facilitative-pattern check, edge cases.}

## Recommendations

1. {Highest impact — resolves N observations}
2. ...

2. report-data.json

This is consumed by scripts/generate-html-report.py. Use the field names exactly. Arrays may be empty [] but must exist.

{
  "meta": {
    "skill_name": "the-skill-name",
    "skill_path": "/full/path/to/skill",
    "timestamp": "2026-03-26T23:03:03Z",
    "scanner_count": 6
  },
  "narrative": "2-3 sentence synthesis shown at top of report",
  "grade": "Excellent|Good|Fair|Poor",
  "broken": [
    {
      "title": "Short headline",
      "file": "relative/path.md",
      "line": 25,
      "detail": "Why it's broken and what goes wrong",
      "action": "Specific fix",
      "severity": "critical|high",
      "source": "which-scanner"
    }
  ],
  "opportunities": [
    {
      "name": "Theme name",
      "description": "What's happening and why it matters",
      "severity": "high|medium|low",
      "impact": "What fixing this achieves",
      "action": "One coherent fix instruction for the whole theme",
      "finding_count": 9,
      "findings": [
        {
          "title": "Individual observation headline",
          "file": "relative/path.md",
          "line": 42,
          "detail": "What was observed",
          "source": "which-scanner"
        }
      ]
    }
  ],
  "strengths": [
    {
      "title": "What's strong",
      "detail": "Why it matters and should be preserved"
    }
  ],
  "detailed_analysis": {
    "architecture": {
      "assessment": "1-3 sentence summary from architecture scanner",
      "findings": []
    },
    "determinism": {
      "assessment": "1-3 sentence summary from determinism scanner",
      "token_savings": "estimated total from script opportunities",
      "findings": []
    },
    "customization": {
      "assessment": "1-3 sentence summary from customization scanner",
      "posture": "opted-in|not-opted-in|over-extended",
      "findings": []
    },
    "enhancement": {
      "assessment": "1-3 sentence summary from enhancement scanner",
      "journeys": [
        {
          "archetype": "first-timer|expert|confused|edge-case|hostile-environment|automator",
          "summary": "Brief narrative of this user's experience",
          "friction_points": ["moment where user struggles"],
          "bright_spots": ["moment where skill shines"]
        }
      ],
      "autonomous": {
        "potential": "headless-ready|easily-adaptable|partially-adaptable|fundamentally-interactive",
        "notes": "Brief assessment"
      },
      "findings": []
    }
  },
  "recommendations": [
    {
      "rank": 1,
      "action": "What to do",
      "resolves": 9,
      "effort": "low|medium|high"
    }
  ]
}

Required field names: meta.skill_name, opportunities use name and finding_count, strengths are objects with title and detail, recommendations use action and numeric rank, journeys use archetype / summary / friction_points / bright_spots, autonomous uses potential / notes. The four detailed_analysis keys are architecture, determinism, customization, enhancement.

Write both files to {quality-report-dir}/.

Return

Return only the path to report-data.json when complete.