The deep dive · chapter 2 · 6 steps

How much process is enough

Choosing between five workflows so a one-line fix doesn't get treated like a new subsystem — and why the choice is about the kind of work, not its size.

1. 1. The problem — process you route around

   Any process that treats a typo the same as a new subsystem gets abandoned for the typo. Then, because you've abandoned it once, you abandon it for the small feature too. Within a month the process applies only to the work nobody minds slowing down, which is not the work that needed it.

   This is why AIDLC doesn't have a process. It has five, and picking the right one is the first real decision on any piece of work.

2. 2. Five workflows, three amounts of ceremony

   Step through the same tool making three different amounts of noise:

   The same tool, three amounts of process

   aidlc — zsh

   $ aidlc start micro-task --name fix-typo
   
   Lifecycle instance created:
     Template: micro-task
     Scope:    micro
     Phases:   implementation → testing

   what you owe

   code-complete.md
   test-results.md
   
   Two documents. That is all.

   ← backstep 1 of 3next →

   Each of those named workflows — AIDLC calls them templates — fixes which steps the work runs through and which documents it owes. There are five:

   • micro-task — implementation and testing. For changes where the design decision was made years ago.
   • bugfix — reproduce it, fix it, test it, ship it. No design step.
   • quick-feature — requirements through deployment. For a feature whose shape is already obvious.
   • full-feature — all seven steps, with a hostile review of the requirements and the design.
   • spike — for a question you can't answer without experimenting. Ends in a findings document, not a change.

3. 3. The word that catches everybody out

   How far back the work starts has a name — scope — and it's the single most misread word in the framework.

   It does not mean how big or how ambitious the change is. It means which steps apply:

   • micro starts at implementation.
   • standard starts at requirements.
   • full starts at ideation.

   So a small change can be full and a large one can be standard. What decides it is whether the problem still needs exploring. If you already know what you want and only need to write it down precisely, starting at ideation is theatre. If you don't yet know what the right behaviour would be, skipping ideation means you'll invent it halfway through implementation, undocumented.

   Ask it as one question: do I know what this should do? If yes, standard. If no, full. If the answer is "this is not a decision, it's a chore" — micro.

4. 4. Your turn

   your turn · Pick the amount of process

   Someone reports that logging in returns a 500 error when the password field is empty. It used to work. Which command starts the right kind of work?

   $ the command that starts this work
   
   Lifecycle instance created:
     Phases:   requirements → implementation → testing → deployment
     First:    reproduction.md — reproduce it before fixing it

   Which line goes in the blank?

   • aidlc start micro-task --name login-500
   • aidlc start full-feature --name login-500
   • aidlc start bugfix --name login-500
   • aidlc start spike --name login-500

   This exercise needs JavaScript. The transcript above is complete apart from the blank.

5. 5. Where the choice usually goes wrong

   Two failure modes, both common.

   Reaching for full-feature because the work feels important. Importance isn't the criterion. A payment change that restores documented behaviour is important and still a bugfix. Running ideation on it produces a document nobody reads, and — worse — it teaches everyone that the documents are decorative.

   Reaching for micro-task because the work feels small. Size isn't the criterion either. The one-line change that needed requirements is the one where nobody could agree afterwards what the line was supposed to do.

   There's a third question that isn't about size at all: is this a change to what the system can do, or a chore the system already supports? Publishing a release note, regenerating a report, rotating a log — those aren't work items at all. They're operations, and they belong in a skill, which chapter eight covers. Wrapping a repeatable chore in seven steps is the fastest way to make anyone hate this.

6. 6. What you can do now

   You can look at a piece of work and answer three questions in about ten seconds: change or chore, do I know what it should do, and is there a design decision to make. Those three answers pick the workflow, and the workflow picks everything else.

   Next: what happens when the tool refuses to let you move on, and why the review is deliberately trying to find fault with your work.