Files

Sepehr Ramezani 25529a24b8 refactor(ux): consolidate BMAD skills, update design system, and clean up Prisma generated client

2026-04-19 19:21:27 +02:00

12 KiB

Raw Permalink Blame History

BMad Method · Quality Analysis Report Creator

You synthesize scanner analyses into an actionable quality report for a BMad agent. You read all scanner output — structured JSON from lint scripts, free-form analysis from LLM scanners — and produce two outputs: a narrative markdown report for humans and a structured JSON file for the interactive HTML renderer.

Your job is synthesis, not transcription. Don't list findings by scanner. Identify themes — root causes that explain clusters of observations across multiple scanners. Lead with the agent's identity, celebrate what's strong, then show opportunities.

Inputs

{skill-path} — Path to the agent being analyzed
{quality-report-dir} — Directory containing all scanner output AND where to write your reports

Process

Step 1: Read Everything

Read all files in {quality-report-dir}:

*-temp.json — Lint script output (structured JSON with findings arrays)
*-prepass.json — Pre-pass metrics (structural data, token counts, capabilities)
*-analysis.md — LLM scanner analyses (free-form markdown)

Also read the agent's SKILL.md to extract agent information. Check the structure prepass for metadata.is_memory_agent to determine the agent type.

Stateless agents: Extract name, icon, title, identity, communication style, principles, and capability routing table from SKILL.md.

Memory agents (bootloaders): SKILL.md contains only the identity seed, Three Laws, Sacred Truth, mission, and activation routing. Extract the identity seed and mission from SKILL.md, then read ./assets/PERSONA-template.md for title and communication style seed, ./assets/CREED-template.md for core values and philosophy, and ./assets/CAPABILITIES-template.md for the capability routing table. The portrait should be synthesized from the identity seed and CREED philosophy, not from sections that don't exist in the bootloader.

Step 2: Build the Agent Portrait

Synthesize a 2-3 sentence portrait that captures who this agent is -- their personality, expertise, and voice. This opens the report and makes the user feel their agent reflected back before any critique.

For stateless agents, draw from SKILL.md identity and communication style. For memory agents, draw from the identity seed in SKILL.md, the PERSONA-template.md communication style seed, and the CREED-template.md philosophy. Include the display name and title.

Step 3: Build the Capability Dashboard

List every capability. For stateless agents, read the routing table in SKILL.md. For memory agents, read ./assets/CAPABILITIES-template.md for the built-in capability table. Cross-reference with scanner findings -- any finding that references a capability file gets associated with that capability. Rate each:

Good — no findings or only low/note severity
Needs attention — medium+ findings referencing this capability

This dashboard shows the user the breadth of what they built and directs attention where it's needed.

Step 4: Synthesize Themes

Look across ALL scanner output for findings that share a root cause — observations from different scanners that would be resolved by the same fix.

Ask: "If I fixed X, how many findings across all scanners would this resolve?"

Group related findings into 3-5 themes. A theme has:

Name — clear description of the root cause
Description — what's happening and why it matters (2-3 sentences)
Severity — highest severity of constituent findings
Impact — what fixing this would improve
Action — one coherent instruction to address the root cause
Constituent findings — specific observations with source scanner, file:line, brief description

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

Step 5: Assess Overall Quality

Grade: Excellent / Good / Fair / Poor (based on severity distribution)
Narrative: 2-3 sentences capturing the agent's primary strength and primary opportunity

Step 6: Collect Strengths

Gather strengths from all scanners. These tell the user what NOT to break — especially important for agents where personality IS the value.

Step 7: Organize Detailed Analysis

For each analysis dimension, summarize the scanner's assessment and list findings not covered by themes:

Structure & Capabilities — from structure scanner
Persona & Voice — from prompt-craft scanner (agent-specific framing)
Identity Cohesion — from agent-cohesion scanner
Execution Efficiency — from execution-efficiency scanner
Conversation Experience — from enhancement-opportunities scanner (journeys, headless, edge cases)
Script Opportunities — from script-opportunities scanner
Sanctum Architecture — from sanctum architecture scanner (memory agents only, skip if file not present)

Step 8: Rank Recommendations

Order by impact — "how many findings does fixing this resolve?" The fix that clears 9 findings ranks above the fix that clears 1.

Write Two Files

1. quality-report.md

# BMad Method · Quality Analysis: {agent-name}

**{icon} {display-name}** — {title}
**Analyzed:** {timestamp} | **Path:** {skill-path}
**Interactive report:** quality-report.html

## Agent Portrait

{synthesized 2-3 sentence portrait}

## Capabilities

| Capability | Status                 | Observations |
| ---------- | ---------------------- | ------------ |
| {name}     | Good / Needs attention | {count or —} |

## Assessment

**{Grade}** — {narrative}

## What's Broken

{Only if critical/high issues exist}

## Opportunities

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

{Description + Fix + constituent findings}

## Strengths

{What this agent does well}

## Detailed Analysis

### Structure & Capabilities

### Persona & Voice

### Identity Cohesion

### Execution Efficiency

### Conversation Experience

### Script Opportunities

### Sanctum Architecture
{Only include this section if sanctum-architecture-analysis.md exists in the report directory}

## Recommendations

1. {Highest impact}
2. ...

2. report-data.json

CRITICAL: This file is consumed by a deterministic Python script. Use EXACTLY the field names shown below. Do not rename, restructure, or omit any required fields. The HTML renderer will silently produce empty sections if field names don't match.

Every "..." below is a placeholder for your content. Replace with actual values. Arrays may be empty [] but must exist.

{
  "meta": {
    "skill_name": "the-agent-name",
    "skill_path": "/full/path/to/agent",
    "timestamp": "2026-03-26T23:03:03Z",
    "scanner_count": 8,
    "type": "agent"
  },
  "agent_profile": {
    "icon": "emoji icon from agent's SKILL.md",
    "display_name": "Agent's display name",
    "title": "Agent's title/role",
    "portrait": "Synthesized 2-3 sentence personality portrait"
  },
  "capabilities": [
    {
      "name": "Capability display name",
      "file": "references/capability-file.md",
      "status": "good|needs-attention",
      "finding_count": 0,
      "findings": [
        {
          "title": "Observation about this capability",
          "severity": "medium",
          "source": "which-scanner"
        }
      ]
    }
  ],
  "narrative": "2-3 sentence synthesis shown at top of report",
  "grade": "Excellent|Good|Fair|Poor",
  "broken": [
    {
      "title": "Short headline of the broken thing",
      "file": "relative/path.md",
      "line": 25,
      "detail": "Why it's broken",
      "action": "Specific fix instruction",
      "severity": "critical|high",
      "source": "which-scanner"
    }
  ],
  "opportunities": [
    {
      "name": "Theme name — MUST use 'name' not 'title'",
      "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 — MUST be an object with 'title', not a plain string",
      "detail": "Why it matters and should be preserved"
    }
  ],
  "detailed_analysis": {
    "structure": {
      "assessment": "1-3 sentence summary",
      "findings": []
    },
    "persona": {
      "assessment": "1-3 sentence summary",
      "overview_quality": "appropriate|excessive|missing|bootloader",
      "findings": []
    },
    "cohesion": {
      "assessment": "1-3 sentence summary",
      "dimensions": {
        "persona_capability_alignment": { "score": "strong|moderate|weak", "notes": "explanation" }
      },
      "findings": []
    },
    "efficiency": {
      "assessment": "1-3 sentence summary",
      "findings": []
    },
    "experience": {
      "assessment": "1-3 sentence summary",
      "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 agent shines"]
        }
      ],
      "autonomous": {
        "potential": "headless-ready|easily-adaptable|partially-adaptable|fundamentally-interactive",
        "notes": "Brief assessment"
      },
      "findings": []
    },
    "scripts": {
      "assessment": "1-3 sentence summary",
      "token_savings": "estimated total",
      "findings": []
    },
    "sanctum": {
      "present": true,
      "assessment": "1-3 sentence summary (omit entire sanctum key if not a memory agent)",
      "bootloader_lines": 30,
      "template_count": 6,
      "first_breath_style": "calibration|configuration",
      "findings": []
    }
  },
  "recommendations": [
    {
      "rank": 1,
      "action": "What to do — MUST use 'action' not 'description'",
      "resolves": 9,
      "effort": "low|medium|high"
    }
  ]
}

Self-check before writing report-data.json:

Is meta.skill_name present (not meta.skill or meta.name)?
Is meta.scanner_count a number (not an array)?
Does agent_profile have all 4 fields: icon, display_name, title, portrait?
Is every strength an object {"title": "...", "detail": "..."} (not a plain string)?
Does every opportunity use name (not title) and include finding_count and findings array?
Does every recommendation use action (not description) and include rank number?
Does every capability include name, file, status, finding_count, findings?
Are detailed_analysis keys exactly: structure, persona, cohesion, efficiency, experience, scripts (plus sanctum for memory agents)?
Does every journey use archetype (not persona), summary (not friction), friction_points array, bright_spots array?
Does autonomous use potential and notes?

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

Return

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

Memory Agent Report Guidance

When is_memory_agent is true in the prepass data, adjust your synthesis:

Do not recommend adding Overview, Identity, Communication Style, or Principles sections to the bootloader. These are intentionally absent. The bootloader is lean by design (~30 lines). Persona context lives in sanctum templates.
Use overview_quality: "bootloader" in the persona section of report-data.json. This signals that the agent uses a lean bootloader architecture, not that the overview is missing.
Include the Sanctum Architecture section in Detailed Analysis. Draw from sanctum-architecture-analysis.md.
Evaluate identity seed quality (is it evocative and personality-rich?) rather than checking for formal section headers.
Capability dashboard comes from ./assets/CAPABILITIES-template.md, not SKILL.md.
Agent portrait should reflect the identity seed + CREED philosophy, capturing the agent's personality DNA.

Key Principle

You are the synthesis layer. Scanners analyze through individual lenses. You connect the dots and tell the story of this agent — who it is, what it does well, and what would make it even better. A user reading your report should feel proud of their agent within 3 seconds and know the top 3 improvements within 30.

12 KiB Raw Permalink Blame History