Spec

Skill: pageship-spec

A spec is a contract between the people who ask for a change and the people who build and test it. Builders are held to every line, so every line is a decision the source made. Everything else is an open question. A spec describes behaviour, not how it is built, and names no file path or line number.

Your agent picks a spec when the reader needs to know what to build and how to tell that it works, such as a feature request turned into requirements.

What the reader gets

The parts come in this order:

1. Title and summary. Two or three sentences in the source’s words: what will change, for whom, and the problem it solves. When there are open questions, the summary gives their number as a link to them.
2. Problem. What is wrong today and for whom, with the evidence the source gives.
3. Solution. What changes for the people the problem affects.
4. User stories. Numbered, one per need the source states: “As a actor, I want behaviour, so that reason.”
5. Acceptance criteria. A numbered list, one criterion per item, each with its own link target such as #ac-1.
6. Implementation decisions. Rules, limits, timings people notice, who sees what, and the contracts between parts.
7. Testing decisions. What the source says will be tested, against which data, by whom, and when.
8. Out of scope.
9. Assumptions. Only when the source states some.
10. Open questions. Every proposal nobody agreed to, everything the source calls undecided, and every gap a builder would hit.
11. Sources.

How it writes acceptance criteria

The agent writes one criterion for each outcome of each decision. Each criterion:

• covers one situation, one event and one result;
• starts from something a user or tester can see happen;
• adds no time limit, threshold, count or place the source doesn’t give. The agent marks a missing value inside the criterion, such as “within [time not given in the source]”, and lists it as an open question;
• has a result that would fail if the change were missing;
• reads on its own, without pointing to another criterion.

Build details such as storage, scheduled jobs and tasks like “add a column” stay out. The agent lists what it left out when it hands over the file.

Patterns it often uses

• Diagrams for a flow or the states something moves through.
• Tables for limits and rules with several values.

Example request

Write a spec for invoice reminders from the thread in reminders-discussion.md.
Only include what we agreed; list the rest as open questions.