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.

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