| name | spec |
| description | Generate a feature spec with user stories directly from conversation context and codebase exploration — no interview needed. Use this when the user has already described what they want (in the current conversation, a doc, or a plan) and just needs it formalized into a spec. Also use when the user says "write a spec", "create a spec", "spec this out", or similar. |
Generate a comprehensive feature spec with user stories by synthesizing information already available in context — conversation history, referenced documents, and codebase exploration. Skip any interview or Q&A phase.
How to gather information
Instead of asking the user questions, proactively resolve unknowns by:
- Mining the conversation: Extract every detail the user has already shared — requirements, constraints, examples, preferences, edge cases mentioned in passing.
- Exploring the codebase: Look at existing patterns, related features, navigation structure, roles, and state management to fill gaps. Check controllers, services, templates/views, and domain logic relevant to the feature.
- Reading project docs: Check
docs/ for architecture docs, onboarding flows, and existing specs that inform the design.
- Making reasonable assumptions: Where information is genuinely missing and can't be inferred from codebase/docs, state your assumption explicitly in the spec (mark with "Assumption:").
Required coverage
The spec must address all of these, even if the user didn't mention them explicitly — infer from codebase patterns:
- Entry points: Where does the user navigate FROM? What existing page/nav/button changes?
- User journey: Complete flow from discovery → interaction → completion → return
- Roles: Which roles interact? Identify all user roles from the codebase (or check
references/project.md).
- Edge cases: Error states, empty states, concurrent access, mobile vs desktop
- State transitions across roles: Which roles see each change? How (real-time — SSE/websockets, polling, refresh)? What does each role's screen show before/after?
- Terminal states: What does the user do next at every end-state? Every screen must have a forward action. URL params, cookies, or tokens needed?
Output format
Write the spec to docs/dev/YYYY-MM-DD-hh-mm_spec-<feature-name>.md and open it with idea (or your editor).
The spec must end with a structured ## User Stories section:
## User Stories
- **US-1**: As a [role], I [action] so that [outcome].
- **US-2**: As a [role], I [action] so that [outcome].
...
Rules for user stories:
- Every user role that interacts with the feature must have at least one story
- Navigation/entry point stories come FIRST
- Cover the happy path, key error states, and edge cases
- Stories must be specific enough to verify — "I can use the feature" is too vague
- Number them (US-1, US-2, ...) so the plan can reference them
Project Customization
Read references/project.md in this skill's directory if it exists. It provides project-specific context:
- User roles and their permissions
- View layer technology (e.g. ViewComponents, Thymeleaf, JSP, React)
- Real-time transport preference (SSE, websockets, polling)
- Output directory conventions
- Any other project-specific patterns
