Add product-spec skill

[norbert-pap]

What

New product-spec skill for the claudebert workflow. Turns a stakeholder brain-dump into a single product handoff spec — one document that makes the work actionable for designer, engineer (and their coding agents), and PM without further meetings.

How it works

A tighter, output-shaped variant of superpowers:brainstorming — same explore → question → approaches → sectioned-review flow, but the terminal artifact is a fixed 8-section handoff format and process meta-commentary is stripped from the final doc.

1. Explore the codebase first — before any questions, so the spec carries concrete real file pointers instead of abstractions
2. Clarifying questions, one at a time, recommendation-led
3. Propose 2–3 approaches for genuine architectural forks only
4. Sectioned review with approval per section (visual mockups for spatial questions, terminal for conceptual)
5. Write the spec to a file, commit it
6. Push + open PR as the handoff

The 8-section format: Big picture · Lifecycle/core flow · UI intent · How it works · Edge cases · Test/deploy/instrumentation · Decisions log · Follow-ups.

Validation

evals/evals.json ships with 3 test prompts + assertions.

• Artifact quality (iteration-1 benchmark): 100% assertion pass rate with-skill vs 16% baseline (no skill). With-skill runs consistently produced the exact 8-section format, ≥2 mermaid diagrams, populated decisions log, and ≥3 cited real file paths that exist in the repo.
• Trigger accuracy: 19/20 on a 20-query eval set — 10/10 should-NOT-trigger queries correctly stayed quiet (no false-positives on adjacent skills: eng-review, prod-review, code-review, brainstorming, design-doc, qa), 9/10 should-trigger fired at 100%. The single miss references "the feature I described above" and only fails under stateless eval (no conversation context).

Notes

• Scoped to only product-spec/ — the orchestrator (claudebert/SKILL.md) is not wired up in this PR to avoid tangling with other in-progress branch work. Add option B → /product-spec to the orchestrator separately.

🤖 Generated with Claude Code