chore: initial monorepo scaffold + WDS Phase 1+2 artifacts
- Nx 22.7 monorepo (pnpm 11.1, TypeScript 5.9, Node 24) - apps/api: NestJS 11 (CJS conforme CODING-RULES.md PGD-DB-004) - apps/web: React 19 + Vite 8 (ESM) - libs/shared/api-interface: Zod contract base - Docker Compose dev: Postgres 18, Valkey 8, MinIO, Mailpit - WDS artifacts: - design-artifacts/A-Product-Brief/ (5 docs canônicos + 16 dialogs) - design-artifacts/B-Trigger-Map/ (hub + 4 personas + feature impact) - Stack canon: STACK.md v2.2 + CODING-RULES.md v2.0 + brand.md - AGENTS.md + README.md como entrada para devs/agentes Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,182 @@
|
||||
# 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
|
||||
|
||||
```markdown
|
||||
# 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.
|
||||
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
Reference in New Issue
Block a user