# Speccy > Deep-dive interview skill for creating comprehensive specifications. Reviews existing code and docs, then interviews the user through multiple rounds of targeted questions covering technical implementation, UI/UX, concerns, and tradeoffs. Produces a structured spec in specs/. Use when starting a new feature, system, or major change that needs a spec. - Skill: `slamb2k/speccy` (Agent Skill, multi-file: 10 files) - Install (CLI): `npx skillmds@latest add slamb2k/speccy` - Raw SKILL.md: https://api.skillmd.com/api/skills/slamb2k/speccy/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: slamb2k (https://skillmd.com/u/slamb2k) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/slamb2k/speccy --- # Speccy - Interview-Driven Specification Builder When this skill is invoked, IMMEDIATELY output the banner below before doing anything else. Pick ONE tagline at random โ€” vary your choice each time. CRITICAL: Reproduce the banner EXACTLY character-for-character, including the diagonal `/` glyph before the name. ``` {tagline} /$$ /$$$$$$ /$$$$$$$ /$$$$$$$$ /$$$$$$ /$$$$$$ /$$ /$$ /$$//$$__ $$| $$__ $$| $$_____/ /$$__ $$ /$$__ $$| $$ /$$/ /$$/| $$ \__/| $$ \ $$| $$ | $$ \__/| $$ \__/ \ $$ /$$/ /$$/ | $$$$$$ | $$$$$$$/| $$$$$ | $$ | $$ \ $$$$/ /$$/ \____ $$| $$____/ | $$__/ | $$ | $$ \ $$/ /$$/ /$$ \ $$| $$ | $$ | $$ $$| $$ $$ | $$ /$$/ | $$$$$$/| $$ | $$$$$$$$| $$$$$$/| $$$$$$/ | $$ |__/ \______/ |__/ |________/ \______/ \______/ |__/ ``` Taglines: - ๐Ÿ” Tell me everything... - ๐Ÿง  Let's think this through! - ๐Ÿ“‹ Spec it before you wreck it! - ๐ŸŽค Interview mode: ACTIVATED - ๐Ÿ’ก Great specs start with great questions! - ๐Ÿ—๏ธ Measure twice, code once! - ๐Ÿ“ No assumption left behind! - ๐ŸŽฏ Precision engineering starts here! --- ## Output Formatting After the banner, display parsed input: ``` โ”Œโ”€ Input โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ โ”‚ {Field}: {value} โ”‚ Flags: {parsed flags or "none"} โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ ``` Pre-flight results: ``` โ”€โ”€ Pre-flight โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ โœ… {dep} {version or "found"} โš ๏ธ {dep} not found โ†’ {fallback detail} โŒ {dep} missing โ†’ stopping โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ ``` Stage/phase headers: `โ”โ” {N} ยท {Name} โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”` Status icons: โœ… done ยท โŒ failed ยท โš ๏ธ degraded ยท โณ working ยท โญ๏ธ skipped --- Interview the user through multiple rounds of targeted questions to build a comprehensive specification, then write it directly using the spec template in `references/spec-template.md`. Interview prompts and question guidelines: `references/interview-guide.md` Spec template and writing guidelines: `references/spec-template.md` ## Flags Parse optional flags from the request: - `--no-superpowers`: Force the standalone interview even when Superpowers is installed - `--auto`: Run autonomously โ€” run the interview and completeness-gated spec write via `references/autonomous-interview.md` in the plain working directory, then write the pending-build marker and stop. No git state is created (that is `/build`'s find-or-create job). Dispatch only; see Stage 1 and Stage 3 below. ## Pre-flight Before starting, check all dependencies in this table: | Dependency | Type | Check | Required | Resolution | Detail | |-----------|------|-------|----------|------------|--------| | prime | skill | `ls .claude/skills/prime/SKILL.md ~/.claude/skills/prime/SKILL.md ~/.claude/plugins/marketplaces/slamb2k/skills/prime/SKILL.md 2>/dev/null` | no | fallback | Context loading; falls back to manual project scan | | superpowers | plugin | on-disk glob via scripts/lib/superpowers.js | no | fallback | Defers Stage 2 interview to superpowers:brainstorming when present; see references/superpowers-deferral.md | For each row, in order: 1. Test file existence (check both paths for symlinked skills) 2. If found: continue silently 3. If missing: apply Resolution strategy 4. After all checks: proceed to context gathering --- ## Stage 1: Context Gathering **No git state โ€” spec + marker only (pr-first-autonomous-build.md REQ-012, superseding bundled-approval-handoff.md's REQ-001/REQ-002):** `/speccy` creates no worktree, branch, commit, or PR at any point, in **both** `--auto` and interactive modes. The interview and inference run in the plain invoking working directory; `/speccy` writes only the spec file and the pending-build marker, then stops. All git state โ€” worktree, branch, commit, draft PR โ€” is now created by `/build`'s find-or-create pre-flight the first time `/build {spec}` runs (see Output & Handoff, and `references/autonomous-worktree-lifecycle.md` repo root). **If `--auto`:** read `skills/speccy/references/autonomous-interview.md` and follow it for the rest of this skill instead of the interactive flow below. ### Pre-Spec Location Check Before gathering context, run the shared root-mismatch check from `references/location-check.md` (`{caller}` = "before Stage 1: Context Gathering"). This is independent of the Pre-Spec Branch Check below. ### Pre-Spec Branch Check Before gathering context, check if the user is on a stale branch: ```bash CURRENT=$(git branch --show-current) if [ "$CURRENT" != "main" ] && [ "$CURRENT" != "master" ]; then git fetch origin main --quiet 2>/dev/null BEHIND=$(git rev-list --count HEAD..origin/main 2>/dev/null || echo 0) if [ "$BEHIND" -gt 5 ]; then echo "โš ๏ธ Branch '$CURRENT' is $BEHIND commits behind main." echo " Consider running /sync before building from this spec." fi fi ``` This is advisory only (specs don't modify code) โ€” do not block, continue regardless of the result. Before asking any questions, build a thorough understanding of the project: 1. **Capture GOAL** โ€” the user's argument describing what needs to be specified 2. **Load project context** โ€” invoke `/prime` to load domain-specific context (CLAUDE.md, specs, memory). If /prime is unavailable, fall back to the manual scan below. 3. **Scan the project** (skip items already loaded by /prime): - Read `CLAUDE.md` if present (project conventions, structure, domain) - Scan `specs/` directory for existing specifications - Scan existing design docs for context - Read relevant source code that relates to the GOAL - Check memory for prior decisions or open questions related to the GOAL 3. **Identify knowledge gaps** โ€” what must you learn from the user to write a complete, unambiguous specification? Group gaps into interview categories: - **Architecture & Technical Design** โ€” stack, patterns, data flow, integrations - **Requirements & Scope** โ€” what's in, what's out, must-haves vs nice-to-haves - **UI & UX** โ€” user flows, interaction patterns, accessibility, responsive - **Security & Auth** โ€” authentication, authorization, data protection - **Infrastructure & Deployment** โ€” hosting, CI/CD, environments, IaC - **Data & Storage** โ€” schemas, persistence, migrations, caching - **Testing & Quality** โ€” test strategy, coverage, acceptance criteria - **Concerns & Tradeoffs** โ€” known risks, alternatives considered, constraints --- ## Stage 2: Interview Rounds Conduct multiple rounds of questions using `AskUserQuestion`. Continue until all knowledge gaps are resolved. **Superpowers deferral (soft dependency):** When Superpowers is detected (per the pre-flight check) and the `--no-superpowers` flag is not set, announce `โšก Superpowers detected โ€” deferring requirements interview to superpowers:brainstorming` and use `superpowers:brainstorming` for requirements/gap exploration in place of (or ahead of) the multi-round interview below. In ALL cases โ€” deferred or standalone โ€” speccy still writes `specs/{slug}.md` and the pending-build marker (see `references/superpowers-deferral.md`). When Superpowers is absent or `--no-superpowers` is set, run the standalone interview unchanged. ### Question Rules 1. **4 questions per round maximum** (AskUserQuestion limit) 2. **Non-obvious questions only** โ€” don't ask things you can determine from reading the code or docs. The user's time is valuable. 3. **Recommendations** โ€” where you have an informed opinion based on the codebase, project conventions, or industry best practice, mark one option as recommended by listing it first and appending `(Recommended)` to its label. At least one question per round should have a recommendation where possible. 4. **Concise options** โ€” 2-4 options per question, each with a clear description of implications and tradeoffs 5. **Progressive depth** โ€” start with high-level architecture and scope, then drill into implementation details in later rounds 6. **Build on answers** โ€” use previous round answers to inform next questions. Don't re-ask decided topics. 7. **Track decisions** โ€” maintain a running list of all decisions made. Present this list at the start of each round so the user can see progress. ### Round Structure Each round follows this pattern: 1. **Progress update** โ€” brief summary of decisions made so far (after round 1) 2. **Category label** โ€” which interview category this round covers 3. **Questions** โ€” 3-4 targeted questions via AskUserQuestion 4. **Evaluate** โ€” after answers, determine if more questions are needed ### Completion Criteria Stop interviewing when ALL of the following are true: - All identified knowledge gaps have been addressed - No answer has raised new unresolved questions - You have enough information to write every section of the spec template - The user has confirmed scope boundaries (what's in and what's out) When complete, briefly present a **Decision Summary** โ€” a numbered list of all decisions made across all rounds โ€” and confirm with the user before proceeding to spec generation. --- ## Stage 3: Generate Specification **If `--auto`:** this stage runs in a subagent (REQ-033) and the completeness gate decides `autonomy_ready` โ€” see `references/autonomous-interview.md`. **Interactive mode (REQ-007):** before writing the spec, self-review it against the same completeness gate โ€” criteria in `references/autonomous-interview.md`'s Stage 3. Set the `autonomy_ready` frontmatter field to `true` when every gate item passes, `false` otherwise; the gate is no longer `--auto`-exclusive. Once the interview is complete and decisions are confirmed: 1. **Create `specs/` directory** if it doesn't exist: ``` mkdir -p specs ``` 2. **Read the spec template** from `references/spec-template.md` 3. **Generate the spec** by filling the template with: - The original GOAL as the introduction and purpose - All decisions from the interview rounds, mapped to the appropriate sections - Code/architecture context discovered in Stage 1 - Acceptance criteria derived from requirements decisions - Test strategy aligned with the project's existing patterns 4. **Write the spec file** to `specs/{name}.md` where `{name}` is a kebab-case slug derived from the GOAL (e.g., `specs/user-auth.md`, `specs/payment-integration.md`). Use the Write tool directly. 5. The `specs/` directory is the standard location โ€” `/build` and `/prime` both scan it automatically. --- ## Output & Handoff **If `--auto`:** invoke `/ferry` to checkpoint before handing off to `/build` (GUD-004) โ€” see `skills/build/references/autonomous-pipeline.md`'s Checkpointing section. After the spec is created, report to the user: ``` โ”Œโ”€ Speccy ยท Report โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ โ”‚ โ”‚ โœ… Spec complete โ”‚ โ”‚ ๐Ÿ“„ File: {spec file path} โ”‚ ๐Ÿ“‹ Sections: {count} โ”‚ ๐Ÿ’ฌ Rounds: {interview rounds conducted} โ”‚ โ“ Questions: {total questions asked} โ”‚ โ”‚ ๐Ÿ“ Key decisions โ”‚ โ€ข {decision 1} โ”‚ โ€ข {decision 2} โ”‚ โ€ข {decision 3} โ”‚ โ”‚ ๐Ÿ”— Links โ”‚ Spec: {spec file path} โ”‚ โ”‚ โšก Next steps โ”‚ 1. Review the spec: {path} โ”‚ 2. Run `/build {spec path}` to implement (reads the file automatically) โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ ``` **Handoff โ€” spec + marker only (pr-first-autonomous-build.md REQ-012):** `/speccy` creates **no git state** โ€” no worktree, branch, commit, or PR. In **both** `--auto` and interactive modes it writes only the spec file (above) and the pending-build marker below, then stops. Worktree/branch/draft-PR creation is now `/build`'s job, done as its find-or-create pre-flight the first time `/build {spec}` runs (see `references/autonomous-worktree-lifecycle.md`, repo root, "Creation โ€” find-or-create" section). To pre-decide the ship-readiness outcome, hand-edit the optional `completion_mode: pr | auto-ship` field into the spec's frontmatter after generation (absent = ask at ship-readiness); `/speccy` does not set it automatically. ```bash PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/marketplaces/slamb2k}" node -e "require('$PLUGIN_ROOT/hooks/lib/state.cjs').savePendingBuild(process.cwd(), '{spec file path}')" ``` This marker is picked up by the session-guard hook on the next session start (including after `/clear`), which surfaces the build command automatically. Then display the build command: ``` โšก To implement, run: /build {spec file path} (You can /clear first โ€” the spec is saved and the next session will remind you) ``` The spec file persists on disk, so the user can `/clear` the conversation to free context before running `/build`. This is the recommended flow for large specs โ€” clearing context gives `/build` maximum working room. **IMPORTANT:** After generating the spec, STOP. Do NOT enter plan mode, do NOT start implementing directly, do NOT invoke `/build` yourself, and do NOT offer to execute the plan. The spec file is the handoff artifact โ€” the user controls when and how to invoke `/build`.