Once you have talked a change through with an agent, the instinct is to tell it to build it right there, in the same conversation. Work that way for a while and you find out that:
- everything you discussed rides along into the build, including every option you rejected, costing tokens it never needed;
- nobody else can check the scope before it is built, because it only exists in one person's session;
- afterwards you can't tell what you actually asked, so there is nothing to check the result against and nothing later agents can learn from.
So every change starts as a ticket, written with one skill, /scoping, and is built from that ticket. The skill asks you questions until the scope is clear, and writes the ticket in product language, so a product person or an engineer can check it.
But a ticket per change only works if there is a description of the whole product to scope against. An agent that scopes a change has to know what the product is for, and the code can't tell it: code says how a feature works today, not what it is meant to do or why. So there are two levels of functional documentation. Documents that describe what the product is, one per part, kept up to date with every change. And a ticket per change, that says what that change adds.
Ensure the agents know the intent behind your product
Without these documents, the scoping agent guesses the intent, or asks you what it should already know, and every change drifts a little further from what the product is meant to be. "The agent can work it out from the code" solves the wrong problem: it rebuilds that knowledge from the code on every change, paying in tokens each time, and still guesses the part the code never said.
- Write down what your product is and why each part exists, in documents every agent reads. Write them in product language, one document per part of the product, never one document for the whole product. Then two unrelated changes don't edit the same file at the same time. Write at the right level: "Dashboards help users stay organized" is too high, because no agent can decide anything with it. "The filter is stored in localStorage under a key per dashboard" is too low, because that belongs to the code. Right is what a person sees, how it behaves, and why: "A Dashboard filter narrows the Panels already on a Dashboard. A Panel with no matching Item is not drawn." Cockpit keeps one file per area in docs/product, such as dashboards.md, fixes the words in a glossary, and points every agent to the right document from a table in CLAUDE.md.
- Make the scoping skill read the documents first, and update them with every change. The first question anyone asks about documentation is who keeps it up to date. Nobody does it by hand for long, which is why most documentation drifts. So make it part of the change: the skill that reads the documents before it scopes also records each new rule in the document of the part it touches. A rule is rewritten where it stands rather than added at the end, so the document always says how the product works now, not how it got there.
Scoping a single feature
The ticket holds only the final decision, in words everyone can check, and the build starts from it in a fresh session. A question nobody answered during scoping gets answered by the agent that builds it, by guessing. So the skill has to do the same thorough job on every change, however small.
- Create a
/scoping skill that scopes every change the same way, so no angle gets skipped. Scope by hand and every change gets scoped a little differently: one time you check the existing rules, the next time you forget to ask what the screen should look like. Cockpit's /scoping always takes the same four steps: read the inputs, decide whether it has to be seen first, sharpen fuzzy language, and check the scope is complete before the engineering plan.
- Tell the skill everything you can think of, in any order, and let it turn that into the scope. Writing a complete, structured scope yourself is slow, and you still miss things. The skill reads the product documents and the code first, so it only asks you what it can't find out itself. In Cockpit, the one line "when creating a filtered panel, I'd like to have the ability to group the items per panel" became this ticket, after a round of questions and a throwaway version in the real app.
- Make the skill grill you until no question is left that would change what gets built. Have it ask its open questions in rounds, each with the answer it recommends, until nothing is unclear. And have it refuse to file the ticket while a question is still open whose answer would change the build. Cockpit's skill asks in rounds and checks before it hands off.
- Make the skill decide whether a change needs a mockup before anything is built. A screen that reads fine in a ticket often turns out wrong the moment you see it. For anything new on screen, have the skill decide up front between nothing, a design, or a quick throwaway version in the real app, and say what question that answers. Cockpit's table: nothing when the change follows a pattern already in the app, a design when the screen is new and more than one layout makes sense, and a throwaway version when the doubt is how it works next to what is already there.
- Write every ticket in product language, never file names or steps. Left alone, an agent writes a plan full of which files change and in what order. It looks thorough, but nobody checks it, because the engineer signing off no longer follows the code at that level. A plan too technical to check isn't validated, it's just approved. So write what is wrong and what should happen, so anyone can read it and confirm it is right. Cockpit's ticket template asks for exactly that, and this ticket shows the result: the tab, the menu and the press, not a file or a variable.
- Let the rules in the ticket become the test names, so the build is checked against what you asked. A ticket only helps if the result is checked against it. Turn its rules into the list of tests the build has to write, and use the rules as the test names. In Cockpit, /engineering-plan drafts that list on the same ticket. How the tests themselves are written is in Managing test automation.
- File a ticket for every change, even a small one. A change made from a prompt leaves no record of what was asked. And a ticket can't be a title and a sentence: the build often starts weeks later, with nobody left who remembers the conversation. It doesn't have to be a GitHub issue; a markdown file in a changes folder does the same job. Cockpit's CLAUDE.md runs
/scoping and /engineering-plan before any feature or fix.
- When a build misses, fix a small miss in its own ticket, and for a big one, rewrite the ticket and build again from scratch. Fixing forward used to be the only economical choice, because writing code was slow. That is no longer true, but the habit stayed. There are three cases:
- the build missed a ticket that was right: fix the code and leave the ticket alone;
- the ticket was wrong and the correction is small: fix forward, but as its own small ticket rather than a prompt, so later agents can learn from it;
- the ticket was wrong in a bigger way: revert, update the ticket with the corrections you already made, and build again from a clean session.