From spec to merged PR

For anything bigger than an afternoon, don't ask for the code first. Ask for the spec, check it, and then build it one task at a time. Each step produces something you can read, so you're steering with documents instead of arguing with a diff.

This guide follows one feature, refunds for a sample payments service, from request to merge.

1. Start with the request

Write down what you want in plain language. A few sentences is enough, but include who it's for and anything you already know about constraints:

"Write a feature specification for partial refunds. Support staff need to refund part of an order from the admin panel. Refunds must be idempotent because the payment provider retries webhooks. It has to work with the existing ledger in services/ledger/."

If the request lives in Jira and you've set up Connectors, point at the ticket instead: "Write a feature specification for PAY-412."

2. Let Slo write the spec

That request triggers the feature specifications workflow. Slo:

  1. Gathers context: your instruction files, the code the feature touches, your knowledge base.
  2. Writes the spec.
  3. Checks it against your conventions and its own list of common gaps, and revises it until it passes.
  4. Splits it into tasks that can each be built and tested on their own.

You get a folder like this:

specifications/12-refunds/
├── overview.md                   what and why, plus a technical map
├── 12.a-refund-model.md          one sub-spec per task
├── 12.b-refund-endpoint.md
└── 12.c-admin-panel-button.md

3. Read the spec. Really.

This is the cheapest place to catch a mistake. A wrong assumption here costs one edit. The same assumption found in review costs a rewrite.

Look for:

  • Scope. Is anything in there you didn't ask for? Is anything missing?
  • Edge cases. What happens with a refund bigger than the order? Two refunds at once?
  • Task order. Can 12.a really be built and tested before 12.b exists?

Ask for changes the same way you'd comment on a colleague's doc:

"In 12.b, refunds over the remaining balance should be rejected, not capped. Also add a task for the audit log entry."

4. Build one task at a time

Now brief the first task. Keep it to one task so each change is small enough to review:

Implement task 12.a only, from specifications/12-refunds/.
Read overview.md and 12.a-refund-model.md first.
Use the code-test-review workflow. Don't commit.
Done means make test passes and the review finds nothing blocking.

The code-test-review workflow writes the code, writes a test for every decision point, reviews the result against your conventions, and checks completion against the spec. It loops until the task is complete.

For bigger tasks, add "use dynamic workflows" and each phase gets its own sub-agent. See Supervise a dynamic workflow.

5. Check it's actually done

Before moving on, ask for a check against the spec, not a summary from memory:

"Is 12.a complete against its spec? List done, partial and missing items with file paths."

Then look at the diff yourself:

/diff services/refunds/model.py

6. Ship it

When you're happy, ask Slo to ship:

"Commit this with a message that explains what changed and why, push to a new branch, and open a merge request."

Slo uses glab for GitLab and gh for GitHub, so have whichever you need installed and signed in. It can go further when you want it to:

"Wait for CI to pass, merge it, then switch back to main and pull."

7. Next task

Proceed to task 12.b. Same rules as before.

Because the spec, the task files and your SLO.md are all on disk, each task starts with the same context, even in a fresh session.