The first agent-ready slice spec I used had five fields: the target UI state, the entity changes, the route, the security scope, and a done line. That was intentional. The project already had a custom /symfony skill carrying the framework conventions, so I did not want to repeat repository rules, CSRF rules, migration naming, routing habits, form patterns, and security-aware query behaviour in every task. The slice spec only had to say what the framework skill could not infer: what the feature looked like, what data existed, which URL owned it, who could use it, and how I would know it was done.
It was enough to start. The first real slices showed it was not enough to plan delivery.
The Original Method Was Deliberately Small
Enough to start.
The early method came out of a practical pressure. I was trying to turn a large rebuild into thin pieces that an AI agent could work on without me manually restating the whole project every time. A feature needed a visible target, a data shape, a URL, a permission boundary, and a pass/fail line. Everything else should come from the project conventions.
The useful role of a framework skill is specific. In this case the skill carried how repositories are built, how query security is preserved, how forms handle CSRF, how migrations are named, how routes are shaped, and which shortcuts are forbidden. Those decisions belong in the convention layer, not in every feature brief.
The five-field spec also kept the work close to the product. It avoided a giant planning document that looked complete while still leaving the actual screen, route, data, permission, or done line ambiguous. For small bounded changes, that was a good trade. It gave a fresh agent enough to start and gave me something concrete to review, but it never forced the import, review-environment, or security-hardening questions onto the page.
The First Slice Answered Back
Missing until named.
The first implementation slice made that limitation measurable. The documented feature estimate was 66 hours. After implementation reality was counted, the same slice modelled closer to 226 hours of traditional effort.
The original method had captured the feature layer: screens, entities, routes, permissions, states, forms, and acceptance criteria. It had not captured the full delivery layer: import work, framework and toolchain integration, security hardening, review infrastructure, seed data, and remediation.
Those misses were not all the same kind of miss. Some were design and review churn after the slice became visible. Some were predictable engineering work that should have had a named place in the plan from the beginning. That distinction matters because a vague contingency percentage would only hide the lesson. The better fix is to make the missing categories show up before implementation starts.
This is where the phrase "feature spec" stopped being precise enough for me. A feature spec says what the user-facing change is meant to do. A delivery spec also asks what has to exist around that change so it can be built, reviewed, imported, secured, deployed, tested, and corrected.
Review Infrastructure Became Part Of Done
The staging work pushed the same lesson from another direction. Once several branches can move at the same time, one shared staging site becomes a coordination bottleneck. A branch might be ready for review while another is waiting for client feedback. A third might need stakeholder review. A fourth might be technically complete but blocked on seeded data.
If all of that work shares one staging URL, every deploy replaces somebody else's review context.
That turned review environments into delivery scope. A review/* branch or worktree should be able to create a stable URL, seed the data, show the branch and build being reviewed, and disappear when the branch is merged, abandoned, or replaced. For some slices that is trivial. For others, especially anything involving legacy data, permissions, workflow changes, or stakeholder feedback, the review environment is part of the work.
The original five fields did not have a natural place for that. The method needed more structure, because a reviewer opening a review/* URL needs evidence of what was seeded, built, and checked.
The Lifecycle Is The Repair
Each step leaves evidence the next step can inspect.
The current lifecycle is simple enough to name in one line: Plan, Design, Specify, Scaffold, Plan implementation, Implement, Verify. The artifact each stage leaves behind is what makes the next stage inspectable.
Plan: slice state
Plan creates the slice boundary and a place for state. It names the work before the project starts absorbing every related concern into one oversized branch. It also creates timing information, so later review can tell which stages actually ran and when.
Design: visible truth
Design captures the visible UI truth before backend structure gets invented from memory. That matters because screens carry quiet requirements: fields, states, labels, grouping, ordering, empty states, permissions, and implied workflow. If those details stay in a screenshot or conversation only, they are easy to lose when implementation starts.
Specify: routes and data
Specify turns the visible work into project artifacts: UI elements, entities, routes, security, requirements, and done criteria. Scaffold then runs before implementation and records what structure could be generated. Even when it generates nothing, the SCAFFOLD.md manifest proves the step was considered. It says this slice did not need new entities, controllers, forms, or tests from the scaffolding pass, rather than leaving that question implicit.
Plan implementation: frozen how
The implementation plan then freezes the work in PLAN.md. That file is the how: task order, tests, files, and implementation moves. It is deliberately different from claude-progress.md, which is the live where: what has been done, what is blocked, what still needs review, and where execution has drifted from the plan.
Implement: live ledger
Implementation keeps the live ledger honest. claude-progress.md matters because the plan is never the whole truth once the work starts; it records what actually changed, where the slice expanded, and which assumptions had to be corrected.
Verify: audit
The audit compares planned scope against actual code and asks which artifacts were missing, incomplete, or misleading. In this case, the 66-hour slice that became 226 hours is what put import work, review infrastructure, seed data, and remediation into the categories for the next slice. Later, the audit itself becomes its own problem: completeness is not a light checklist. It needs serious inspection, enough context, and enough compute to look across the plan, the code, the tests, and the missing work.
Convention Layer And Artifact Layer
This also clarified the difference between the Symfony skill and the SDLC lifecycle. The /symfony skill is the convention layer. It tells the agent how this project builds Symfony: repository patterns, CSRF, routing, migrations, forms, naming, dependency choices, and security rules.
The SDLC lifecycle is the artifact layer around that. It tells the delivery system what has to exist before a handoff is safe. Import work, seeded review data, route security, and rollback checks now have specific places to appear before implementation treats them as settled.
I still want the execution machinery that made parallel agent work useful: fresh subagents, worktree isolation, and review. The missing questions have to sit in the stage where they can still change the work cheaply: a review-environment question before review becomes blocked, an import question before a feature assumes clean data, a security question before generated routes and forms are treated as complete, and a scaffolding manifest before implementation pretends structure has already been settled.
The Useful Test
Fewer invisible assumptions.
The useful test for a planning artifact is whether the next stage can inspect it, act on it, and prove whether it was complete. If it cannot do those three things, the artifact is probably theatre.
Execution speed is the same either way; an incomplete artifact shows up later as review churn, missing import work, security fixes, broken staging, and slices that need to be split after they have already become expensive.
On this project, the 66-hour slice that became 226 hours is the reminder: the missing work has to be visible before speed makes the mistake larger.