# User Spec Planning

> Helps Codex turn a vague idea into a clear feature description before coding starts. Use it when the user knows roughly what they want but requirements, scope, and success criteria are still fuzzy. Good for features, fixes, and refactors that need agreement before implementation. Trigger on requests like: "сделай юзерспек", "продумай фичу", "опиши требования", "user spec", "feature planning".

- Skill: `aggel008/user-spec-planning` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add aggel008/user-spec-planning`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aggel008/user-spec-planning/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: aggel008 (https://skillmd.com/u/aggel008)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/aggel008/user-spec-planning

---


# User Spec Planning

This skill creates a simple planning document for a feature or fix.

Use it when:

- the idea is still vague
- you want to agree on scope before coding
- acceptance criteria are missing
- different people may understand the request differently

Main benefit:

- reduces rework
- makes requirements explicit
- gives implementation a stable target

## Output

Default output:

- `work/<feature>/user-spec.md`

For the recommended structure, read [template.md](references/template.md).

## Workflow

1. Clarify the feature, fix, or refactor in operator language.
2. Read only the relevant project context:
   - `docs/project_knowledge/project.md`
   - `docs/project_knowledge/architecture.md`
   - `docs/project_knowledge/patterns.md`
3. Scan the codebase enough to ground the discussion in reality.
4. Ask focused questions to close gaps in:
   - goal
   - target user
   - desired behavior
   - constraints
   - edge cases
   - acceptance criteria
5. Write `user-spec.md` in language the operator can read quickly.

## Rules

- Prefer short interview batches over a giant question dump.
- Reference existing code and current product direction when useful.
- Challenge unclear requirements with concrete examples.
- Acceptance criteria must be testable.
- If the request is too large or vague, propose splitting the scope.

## Boundary

This skill defines:

- what should happen
- why it matters
- how success is recognized

It does not define:

- low-level implementation design
- file-by-file coding plan
- full task decomposition