What good looks like for each artifact, and the three mistakes that sink most specs. These mirror the print companion's pages 3–9.

Personas

Personas exist to settle arguments. A good one names a role ("freelance developer with a side project"), the goals that brought them here, the pains that make them leave, and their tech comfort, because that changes how much hand-holding you build. Two to four is plenty for a v1.

Most common mistakes

1. Demographic trivia instead of behaviour. Age and city rarely change your feature list; goals and pains do.
2. Personas nothing links to. If no feature names a persona, it's decoration.
3. Five or more personas for a product nobody has used yet.

⚡ VibeMap generates personas like these in minutes → https://vibemap.ai?utm_source=notion&utm_medium=template&utm_campaign=spec-kit

Features

A feature is something a user can do, written with a verb and small enough to demo. Every feature here carries an honest priority, a primary persona, and links to the pages where it lives and the entities it touches. This database is the spine of the spec: stories hang off features, criteria hang off stories.

Most common mistakes

1. Noun features ("Dashboard", "Analytics") that hide what the user actually does.
2. Everything marked High. If all seven are High, none are.
3. No persona link, so nobody can say who the feature is for.

⚡ VibeMap turns one product description into a prioritised, linked feature list in minutes → https://vibemap.ai?utm_source=notion&utm_medium=template&utm_campaign=spec-kit

User Stories

One story is one action by one named persona role, with a real benefit: As a [role], I want [action], so that [outcome]. The "so that" clause is the test. If it restates the action, you haven't found the reason yet, and a feature without a reason is scope creep with a backlog ID.

Most common mistakes