spec

name

spec

description

Turn vague ideas or abstract prompts into detailed, actionable specifications through a grill-me-style decision-tree questioning loop with recommended answers, codebase exploration, web research, and interactive clarification with the user. Invoke when a repository-change request is too vague or abstract for /plan — missing objective, scope, or acceptance criteria. Do not invoke for reviews, Q&A or explanations, execution of an existing plan, trivial fixes, or when the user explicitly requests another skill.

Turn an abstract idea into a detailed specification.

Role separation: /spec vs /plan

Aspect	/spec	/plan
Input	Vague idea, abstract prompt	Clear spec, defined task
Focus	What to build (requirements, constraints)	How to build (implementation strategy, files)
Output	Spec doc (docs/specs/*.md) / GitHub issue	Implementation plan (docs/plans/active/*.md)
Research	Codebase exploration, web search, best practices	Affected files, risk analysis
User interaction	Decision-tree questioning with recommended answers + clarification	Flow selection (standard/Ralph) + critical-fork resolution (convergent)

/spec comes before /plan. Use /spec when the request is too vague for /plan.

Goals

• Transform ambiguous requests into implementation-ready specifications
• Expand sparse inputs (even a one-line prompt) through decision-tree questioning with recommended answers
• Discover requirements through codebase analysis and best-practice research
• Resolve residual ambiguity through targeted user questions
• Produce a versioned spec that survives context loss
• Isolate every temporary or versioned spec artifact in a clean-base task worktree before writing it

Steps

1. Understand the request (internal, no user interaction): Read the user's input. List what is clear and what is ambiguous or missing. This is an internal triage step — do NOT call AskUserQuestion here. The list feeds the next step.

2. Interrogate the decision tree with research-backed questions: Use AskUserQuestion iteratively to question the user about every aspect of the spec until there is shared understanding. Treat this as a grill-me-style planning loop, not as an open-ended ideation pass.

   • Walk the design tree branch by branch, resolving upstream decisions before downstream ones and making decision dependencies explicit.
   • Ask questions in batches of five, unless fewer than five unresolved decisions remain.
   • For every question, include the recommended answer and a short rationale so the user can accept, reject, or refine it.
   • When the user asks questions or challenges a recommendation, answer directly, update the decision map, and then continue the loop.
   • As the user answers, maintain an in-memory decision map/spec outline with resolved decisions, rejected alternatives, dependencies, and remaining branches.
   • Before asking any question, check whether codebase exploration can answer it. If the repository answers the question, investigate instead of asking, record the evidence, and move to the next unresolved decision.
   • Explore inline for existing related code, current patterns and conventions, impact areas, dependencies, and similar implementations.
   • When a branch depends on external best practices, current library/framework behavior, or reference implementations, use WebSearch/WebFetch or Context7 MCP as appropriate before asking the user to decide.
   • Continue until the user signals that the idea is sufficiently shaped, or until additional questions stop producing new implementation-relevant information.
   • Respect anti-bottleneck: ask only for genuine product, scope, or trade-off decisions that cannot be resolved from repo context, research, or a reasonable default.

3. Clarify residual requirements: Use AskUserQuestion only for ambiguity that remains after the decision-tree loop:

   • Underspecified aspects surfaced by exploration/research
   • Trade-off decisions informed by newly gathered context (e.g., simplicity vs extensibility)
   • Priority and scope boundaries not yet nailed down
   • User preferences and constraints tied to findings
   • Ask in batches of five with recommended answers when several residual decisions remain.
   • Purpose is — narrow toward a single, implementable spec.

Anti-bottleneck

Before asking the user a question, first check whether you can answer it by:

• Inspecting the codebase (existing patterns, conventions, tests)
• Reading existing docs or plans
• Running scripts or checks
• Choosing a reasonable default and documenting it

Only use AskUserQuestion for genuine ambiguity that cannot be resolved from repo context. See the anti-bottleneck skill for the full checklist.

Output

• Spec file at docs/specs/<date>-<slug>.md
• Or GitHub issue with spec content and immediate spec worktree cleanup
• Or docs/spec PR with immediate spec worktree cleanup
• Or /plan skill invocation for immediate implementation planning in the same worktree

CLI execution modes

This skill runs under both Claude Code and Codex. The execution mode follows the conventions in AGENTS.md and .codex/AGENTS.override.md.

Aspect	Claude Code	Codex
Skill invocation	/skill-name slash command	$skill-name mention or the /skills menu (avoid the /skill-name form — it collides with built-ins)
Skill body path	.claude/skills/<name>/SKILL.md	.agents/skills/<name>/SKILL.md
Subagent mechanism	Task(subagent_type=...) when a policy delegates	.codex/agents/ custom agents when a policy delegates
Structured prompts	AskUserQuestion	Numbered options printed to stdout, awaiting a digit reply
Artifacts	docs/reports/, docs/plans/, docs/specs/ (shared)	Same (CLI-agnostic)

The drift check (./scripts/check-skill-sync.sh) cross-checks both bodies and invocation metadata — editing only one side will fail CI.