feat: spec enhancer skill — auto-detect missing details and default to Tailwind v4 + shadcn/ui

[rubenmarcus]

Problem

When a spec is vague or missing key decisions (like UI library choice), the ralph-starter loop generates code with subtle but critical issues that pass npm run build but produce a completely broken UI.

Real-world example

A spec said:

"No UI library — just plain CSS or CSS modules"

The loop generated page.tsx with one set of class names (btn, btn-primary, feature-title, hero-stats) and page.css with completely different CSS selectors (.cta-button.primary, .card-title, no .hero-stats at all). The build passed (TypeScript doesn't validate CSS↔HTML class name matches), but the page was completely broken — text clipped off the left edge, buttons invisible, stats unstyled, SVG icons rendering as giant nested rectangles.

Root cause: Plain CSS in separate files is inherently fragile for AI code generation because there's no compile-time link between CSS selectors and JSX classNames. The loop has no feedback mechanism to catch this class of bug.

Proposal: Spec Enhancer Skill

A Claude Code skill (or built-in ralph-starter behavior) that runs before the implementation loop and:

1. Detects underspecified areas in specs

Scan the spec for missing decisions and flag them:

• UI library: If the spec doesn't explicitly say "use plain CSS" or "no UI library", default to Tailwind CSS v4 + shadcn/ui (prevents CSS↔HTML mismatch entirely since styles are utility classes in JSX)
• Package versions: If versions aren't pinned, resolve to latest stable
• File structure: If not specified, generate an explicit file tree
• Design requirements: If the spec says "dark theme" but doesn't specify colors, contrast, spacing, add sensible defaults

2. Enhances the spec with implementation-level detail

Transform vague specs into highly specific ones:

Before:

- Landing page with hero section and features grid
- Dark theme
- Mobile responsive

After:

- Hero section: centered text (text-center), max-w-7xl mx-auto px-6, py-24
  - Badge: shadcn Badge component with variant="secondary"
  - Heading: text-4xl sm:text-5xl md:text-6xl font-bold tracking-tight
  - Subtitle: text-lg text-muted-foreground max-w-2xl mx-auto
  - CTA: two shadcn Buttons (default + outline variant) in flex row
  - Stats: grid grid-cols-3 gap-8 with text values
- Features: grid grid-cols-1 md:grid-cols-3 gap-6
  - Each card: shadcn Card with CardHeader + CardContent
  - Icon: emoji or unicode in a rounded-lg bg container (NO custom SVGs)
- Dark theme: class="dark" on html, CSS variables per shadcn defaults
- All styling via Tailwind utility classes — NO separate CSS files for components

3. Generates a granular IMPLEMENTATION_PLAN.md

Break down into atomic steps that the loop can verify:

- [ ] npm install (verify: package-lock.json exists, node_modules/next/package.json shows v15+)
- [ ] postcss.config.mjs with @tailwindcss/postcss (verify: file exists with correct content)
- [ ] globals.css with Tailwind v4 4-step pattern (verify: @import "tailwindcss", :root vars, @theme inline, @layer base)
- [ ] src/lib/utils.ts with cn() (verify: exports cn function using clsx + twMerge)
- [ ] shadcn Button component (verify: src/components/ui/button.tsx exports Button)
- [ ] shadcn Card component (verify: src/components/ui/card.tsx exports Card, CardHeader, etc.)
- [ ] layout.tsx with Inter font + dark class (verify: html has className="dark")
- [ ] page.tsx with ALL Tailwind utilities (verify: NO page.css exists, page.tsx uses className= with Tailwind classes)
- [ ] npm run build passes
- [ ] npm run dev serves at localhost:3000

4. Smart defaults

Missing from spec	Default to
UI library not specified	Tailwind CSS v4 + shadcn/ui
CSS approach not specified	Utility classes in JSX (no separate CSS files)
Font not specified	Inter via next/font/google
Package versions not pinned	Latest stable (Next.js 15+, React 19)
Design system not specified	shadcn/ui with zinc base color
Build tool not specified	PostCSS for Next.js, Vite plugin for Vite

5. Invoke design skills automatically

If the spec involves UI, automatically invoke:

• /frontend-design — production-grade interface design
• /tailwind-v4-shadcn — correct Tailwind v4 + shadcn setup
• /responsive-web-design — responsive layouts
• /web-design-guidelines — UI best practices

Why this matters

The ralph-starter loop is great at executing well-specified tasks, but it can't catch design/visual bugs because:

1. npm run build doesn't validate CSS↔HTML class name matches
2. There's no visual regression testing in the loop
3. Plain CSS is inherently fragile for AI code generation

Tailwind utility classes eliminate the entire class of CSS↔HTML mismatch bugs because styles are co-located with markup. This should be the default, not an opt-in.

Implementation ideas

• Could be a Claude Code skill in skills.sh/ that users can add
• Could be a built-in ralph-starter plan enhancement
• Could run as a pre-loop step in ralph-starter run
• Could be a --enhance-spec flag

Happy to contribute if there's interest.