product-spec-builder

---

name: product-spec-builder description: Used when the user says they want to build a product, application, or tool, or when they want to add features, change requirements, or adjust UI. Collects requirements through in-depth conversation, generates or updates Product-Spec.md. version: 1.1.0 updated: 2026-05-30 requires: []

[Task] 0-to-1 Mode: Collect product requirements from the user through in-depth conversation, using direct even pointed questioning to force the user to think clearly, ultimately generating a structurally complete, detail-rich Product Spec document suitable for direct AI development, and output it as a .md file for the user.

**Iteration Mode**: When the user proposes new features, requirement changes, or iterative ideas during development, use questioning to help the user clarify the change, detect conflicts with the existing Spec, directly update the Product Spec file, and automatically record the changelog.

[Not For] - Creating development plans -> use /dev-planner instead - Writing code -> use /dev-builder instead - Designing visual style -> use /design-brief-builder instead - Fixing bugs -> use /bug-fixer instead

[Dependency Check] Executed automatically as the first step when the Skill starts. All checks must pass before entering the main workflow.

This skill has no external dependencies, only pre-requisite file checks:
- 0-to-1 Mode: No pre-requisite files required
- Iteration Mode: Product-Spec.md must exist

[First Principles] Spec 前必读 references/first-principles.md

[Shared Discipline] Karpathy 四原则 → ../_shared/karpathy-discipline.md

[HARD-GATE] Until Product-Spec.md is saved and the user explicitly confirms it (0-to-1) or confirms the iteration delta (Iteration Mode):

- **MUST NOT** invoke `/dev-planner` or `/dev-builder`
- **MUST NOT** create or edit application source under `src/`, `app/`, `lib/`, `packages/`
- **MUST NOT** treat "rough agreement in chat" as confirmation — user must confirm the written Spec (or changelog delta)

Session-start iron laws reinforce this via `templates/forge-bootstrap.md` (injected by `check-evolution` hook).

Rationalizations → `references/hard-gate-rationalization.md`

[File Structure] product-spec-builder/ ├── SKILL.md # 入口（本文件） ├── references/ │ ├── first-principles.md │ ├── output-style.md │ ├── skills-capabilities.md │ ├── judgment-spectrum.md │ ├── startup-check.md # 模式路由 │ ├── workflow-quick-mode.md # Quick 路径（短 prompt） │ ├── workflow-0-to-1.md │ ├── workflow-iteration.md │ ├── light-grill-mode.md │ ├── distillation-mode.md # 需求蒸馏（反讨好·需求阶段） │ ├── requirements-dimensions.md │ ├── conversation-strategy.md │ ├── hard-gate-rationalization.md │ ├── multi-stakeholder-review.md # 四视角扫描 + 输出格式 │ ├── critique-gate.md # 反讨好偏见批判 gate（三个结构信号） │ └── pm-frameworks-*.md │ └── multi-stakeholder-review.md # 四视角扫描 + 输出格式 └── templates/ ├── product-spec-template.md └── changelog-template.md ../_shared/

[Gotchas] Skipping WebSearch: "I know this domain well" → WebSearch anyway. Competitors, frameworks, and best practices change fast. Accepting vague requirements: "users will like it", "good UX", "modern design" → keep pressing until specifics. Over-scoping: Every "nice to have" is scope creep unless explicitly cut. After collecting requirements, proactively trim: "What can we cut from v1?" Missing conflict detection: In iteration mode, cross-reference existing Spec before finalizing changes. Duplicating change-manager: Do not create changes/<name>/ here — scoped features use /change-manager only. Chat agreement is not HARD-GATE lift: Require explicit confirm of the saved file. See references/hard-gate-rationalization.md. Quick Mode loading wrong refs: Quick path → read workflow-quick-mode.md only; do not load full 0-to-1 interview chain. Cross-phase redundancy: Questions asked in Exploration may be re-asked verbatim in Clarifying or Refinement. Track what's been covered: after each phase, note covered topics; before next phase, scan that list. Do not ask what was already asked. Single-pass validation is insufficient: Step 6 Final Validation must run at least 3 full scan→fix cycles, not just "until clean". One pass misses 30-50% of issues. Use an explicit counter and re-read the full Spec each cycle — incremental diffs accumulate blind spots. No cross-phase dedup before generation: Exploration, Clarifying, and Refinement phases each produce interview notes with overlapping content. Before Document Generation, do a structured dedup pass across all phases' notes — merge duplicate requirements, flag contradictions across phases, consolidate scattered decisions. Redundancy baked into the Spec is much harder to remove after generation. Multi-Stakeholder Review ≠ Critique Gate ≠ Step 7: MS Review asks "should we build this?" Critique Gate asks "what are we getting wrong?" Step 7 asks "is the Spec sound?" Three different gates — do not merge them. Product size → gate level: Small products (CLI, ≤4 features, no auth/DB) get recommended light gate level via forge-size-detect. Full gates for larger products. User may override in .forge/gate-config.json. Critique Gate evidence rule: Every finding in the Critique Gate Summary must cite Evidence as §section or "spec quote". Findings without evidence do not count toward the density quota — unfalsifiable criticisms are the easiest to fake. Critique Gate verdict thresholds: 0 findings + proceed → re-scan mandatory (highest sycophancy risk). <3 evidence-backed findings → re-scan once. ≥3 evidence-backed findings → proceed/clarify/blocked per stop rules. Full procedure in references/critique-gate.md.