feat: add dx-roaster skill

[Karanjot786]

Summary

Adds the dx-roaster skill. It audits a GitHub repo for developer experience and ships a brutally honest verdict you share before launch.

The skill scores 10 DX dimensions, writes a roast in your chosen tone, generates a prioritized fix list ranked by impact and effort, and sketches an ideal README. One input, four output files, ready in under a minute.

Run it before Show HN, Product Hunt, npm publish, or any launch where the first five minutes decide whether visitors stay or bounce.

What this skill does

You point it at a repo path or GitHub URL and pick a tone (brutal, honest, or kind).

The skill scans these files:

• README.md
• CONTRIBUTING.md, CODE_OF_CONDUCT.md, issue and PR templates
• package.json, pyproject.toml, Cargo.toml, go.mod
• LICENSE
• docs and examples folders
• CI badges and recent commit activity

It scores 10 DX dimensions, each 0 to 10:

• Time to first success
• What is this clarity
• Visual proof
• Install simplicity
• Runnable quick start
• Documentation depth
• Examples
• Community signals
• Trust signals
• Marketing signals

Total rolls up to a letter grade. A for 90 plus, B for 75 to 89, C for 60 to 74, D for 40 to 59, F under 40.

Output files

The skill writes four files to dx-roast/:

• roast.md, your shareable verdict, 250 to 500 words
• action-plan.md, 5 to 10 fixes ranked by impact divided by effort
• ideal-readme.md, a sketch of what your README could look like
• score.json, raw scores per dimension plus the grade

The roast is built to be shareable. Post an excerpt as a tweet. Forward to your co-founder. Use it as open build content alongside the fix.

Three tone options

Choose one based on who reads the output:

• brutal, for Twitter shares and last resort wake up calls
• honest, the default, the senior engineer code review voice
• kind, for solo maintainers and first time OSS authors

Every tone stays specific. The skill never names individual maintainers. It roasts the work.

Files in this PR

• skills/dx-roaster/SKILL.md, the agent protocol with 7 steps, self QA, and error handling matrix
• skills/dx-roaster/README.md, your install and usage guide
• skills/dx-roaster/references/scoring-rubric.md, the 10 dimension rubric with explicit 0 and 10 anchors
• skills/dx-roaster/references/roast-voice-guide.md, voice patterns for brutal, honest, and kind
• skills/dx-roaster/references/readme-template.md, the ideal README skeleton with filling rules
• registry.json plus README.md count updates from the auto sync

Design and plan

• Design spec at docs/superpowers/specs/2026-05-22-dx-roaster-design.md
• Implementation plan at docs/superpowers/plans/2026-05-22-dx-roaster.md

Test plan

• Run on the current repo, tone honest, confirm 4 output files appear under dx-roast/
• Check score.json holds all 10 dimensions, total equals sum, grade matches the bands
• Check roast.md references at least 3 specific findings from the scan
• Check action-plan.md has 5 to 10 items sorted by impact divided by effort
• Check ideal-readme.md uses placeholders, never invented URLs
• Re-run with tone brutal, confirm voice shifts
• Re-run with tone kind, confirm voice shifts again
• Pass compare_to and confirm the Benchmark line appears in the terminal summary

[greptile-apps]

Greptile Summary

This PR adds the dx-roaster skill — a multi-step agent protocol that audits a GitHub repo's developer experience across 10 dimensions, writes a tone-aware roast, generates a prioritized fix list, and sketches an ideal README. The supporting reference files (scoring rubric, voice guide, README template) are well-structured and internally consistent.

• SKILL.md defines a 7-step protocol with self-QA and error handling; the action-plan header template carries a persisting impact × effort label that contradicts the impact / effort formula defined in Critical Rule 5 and Step 5, and Step 7's compare_to benchmark output has no corresponding computation step in Steps 1–6.
• references/ files are clean: rubric anchors, grade bands, and voice patterns are consistent throughout.
• registry.json and README.md counter updates are correct.

Confidence Score: 4/5

Safe to merge after addressing the compare_to scoring gap in SKILL.md; the rest of the skill protocol is well-defined.

Step 7 outputs a benchmark score and grade for the compare_to repo, but no step in the protocol instructs the agent to scan or score that repo — leaving the benchmark values undefined. An agent following the steps literally will either omit the line or fill it with a hallucinated number. The action-plan header also still says "ranked by impact × effort" while the formula throughout is impact / effort, which would produce a backwards sort order.

skills/dx-roaster/SKILL.md — the compare_to scan instructions and the action-plan header template both need correction before the skill behaves as documented.

Important Files Changed

Filename	Overview
skills/dx-roaster/SKILL.md	Core agent protocol for the skill; contains the compare_to benchmark computation gap (Step 7 references scores for a second repo that no prior step defines how to produce) and a persisting action-plan header mismatch (impact × effort vs impact / effort).
skills/dx-roaster/README.md	User-facing install and usage guide; contains a stale reference to position-me in the manual install note that was flagged in a prior review.
skills/dx-roaster/references/scoring-rubric.md	10-dimension rubric with explicit score anchors and grade conversion table; definitions are clear and consistent.
skills/dx-roaster/references/roast-voice-guide.md	Voice guide for brutal/honest/kind tones with do/don't lists and opening line examples; no issues found.
skills/dx-roaster/references/readme-template.md	Ideal README skeleton with filling rules; consistent with the broader skill protocol.
packages/cli/registry.json	Adds dx-roaster registry entry with correct metadata (name, description, tags, author, version, path).
README.md	Counter incremented from 59 to 60 in badges, text, and skill table; dx-roaster entry added correctly.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A([User invokes dx-roaster]) --> B{repo param}
    B -- URL --> C[git clone to /tmp/dx-roast-hash]
    B -- local path --> D[Scan in place]
    C --> E[Step 2: Discover files + gh API metadata]
    D --> E
    E --> F[Step 3: Score 10 dimensions → score.json]
    F --> G[Step 4: Write roast.md]
    G --> H[Step 5: Compute priorities → action-plan.md]
    H --> I[Step 6: Fill README template → ideal-readme.md]
    I --> J[Self-QA checklist]
    J -- any check fails --> K[Re-run failed step]
    K --> J
    J -- all pass --> L[Step 7: Print terminal summary]
    L --> M{compare_to provided?}
    M -- yes --> N["⚠️ Benchmark line needs <X>/100\n(no scan step defined for compare_to)"]
    M -- no --> O([Done])
    N --> O
    C -- clone fails --> P([Exit: Repo not found or inaccessible])

Loading

_{Reviews (2): Last reviewed commit: "feat(dx-roaster): updating the SKILL.md ..." | Re-trigger Greptile}