Specs
A spec is the written plan for a story.
It is the clearest statement of what the story is trying to achieve and how success should be judged.
Why specs matter in AIDEN
AI gets much better when the target is clear.
Without a spec, implementation tends to drift. With a spec, AIDEN has a stronger basis for planning, execution, and review.
A spec helps answer:
- What is being built?
- Why does it matter?
- What is included?
- What is not included?
- What should the behavior be?
- What are the acceptance criteria?
What a good spec usually contains
A strong spec often includes:
- summary
- user value
- scope
- requirements
- technical approach
- phases or plan
- acceptance criteria
- risks and edge cases
Not every story needs a huge document, but every meaningful story benefits from clarity.
The role of specs in the workflow
Specs sit between backlog and implementation.
They turn “we should build this” into “this is what good looks like.”
That is what makes later review possible.
Common mistakes
Specs that are too vague
If the spec sounds like the story title repeated with more words, it will not help much.
Specs that are too large for the story
If the plan feels bigger than one meaningful slice, the story should probably be split.
Treating the spec as decoration
The spec should actively guide implementation and review.