---

name: tlc-plan description: 'Turns decided work — a PRD, design doc, RFC, or thread — into tasks a builder can act on without guessing. Finds slices that each prove something, grounds them in the code, and writes intent, observable criteria with concrete values, the boundary, what the change disturbs, and only the decisions that are hard to reverse. Walks every surface the work exposes and sweeps the nine unwritten requirements, recording each landing as a criterion already in the source, existing behaviour, n/a, or Unresolved — never as a criterion the walk invented. Defaults to one task per source. Use when the user says "write the task", "cut this PRD into tasks", "turn this design doc into work", or "tlc-plan". Do NOT use for discovery itself or to implement — a one-line ticket is a decision; a blank wish is not.' license: CC-BY-4.0 metadata: author: Tech Leads Club - github.com/tech-leads-club version: 0.2.0

TLC Plan

Cut the source. Ground it in the code. Write the task.

CUT ──────────→ GROUND ──────────→ WRITE
(slices, then   (the repository     (one task,
 how many        it lands in)        unless a seam
 tasks)                              is forced)

Someone already decided what to build. A one-line ticket counts; a blank "we should do something about billing" does not. This turns that decision into work a builder can pick up without guessing, and stops at the first thing nobody decided. It has no opinion about product: it does not explore the problem, generate options, or grow scope. What it does find is the operational hole the source left implicit - the empty state, the error shape, the flag the job never named - by walking two fixed lists, not by inventing a better feature.

Critical rules

1. Every criterion is an observable outcome with a concrete value. "The columns exist" is not a criterion, and that is the point - a horizontal slice has nothing observable to write, so the format cannot express one.
2. Refuse rather than guess. A gap in the source comes back as a question. A plausible criterion nobody decided is the expensive failure: it reads well, gets approved, and ships.
3. Decided carries only what is hard to reverse, in its literal shape. Everything reversible is decided while building and reviewed in the diff.
4. Raising a concern is free; growing scope is the user's call. Ask about anything you find; add capability nobody asked for, never.
5. When the source contradicts the code, amend the source. Quietly building the right thing leaves the document that five other people read still wrong.
6. The task is the record of decision. Linked documents keep the reasoning and stay editable; if one diverges later, ask before building.

Cut

Read every source completely first - PRD, design doc, RFC, thread. Then enumerate the slices it contains, and only after that decide how many tasks they become. Those are two questions, and collapsing them is where sizing goes wrong.

A slice is one observable outcome, never a layer. "Schema first, then the endpoints" produces pieces nobody can verify alone, and their criteria degenerate into structure - the table exists, the route responds - which proves nothing about behaviour. A slice is right when someone can watch it work.

Vertical is the shape of a slice, not the size of a task. A task holding every slice in the source is still vertical, because every criterion is still an outcome someone can watch. Only the layer cut is unwritable here.

Preparation that proves nothing - a nullable column, a client with no caller - is real work and belongs in a commit or a pull request, but it is not a task, because it has no criterion.

Default to one task for the whole source. Splitting is the exception and needs a reason you can defend from evidence, which narrows it to three: a piece cannot land before another without breaking production, a piece waits on an answer only someone else can give, or a piece belongs to another team. Past those it is preference about how this team likes to work, and preference is not yours to impose - a cut you cannot defend makes the user undo your work before they start theirs.

The default buys something real, too. Every one-way door in the source gets reviewed together, once, where the interactions between them are visible. Split six ways, the same doors arrive in six batches and the abstraction they share grows by accretion, each task adding the minimum its own criteria needed and nobody ever seeing the whole.

Say when it is big. The cost of a large task is not a large pull request - those are independent, and one task routinely becomes several. The cost is how much work gets thrown away when an irreversible decision turns out wrong, because you find out later. So weigh what makes that expensive: how many one-way doors there are, whether a schema migration is among them, and how many slices - in that order. Six slices with no doors is safe whole; three slices with four doors and a migration is not.

When it is big, show the seams that exist instead of a number you made up. Order constraints first, marked as the kind that cannot be collapsed, then the thematic groupings, each with the reason it is a seam. Let the user pick where to cut. A round number the skill suggests is an opinion dressed as arithmetic.

Sizing evidence, in order. What the project declares wins: a contributing rule, a team convention doc. Then the issue tracker, if it is reachable - task size is a tracker property, and git history only ever reveals pull request size, which is a different question. Then ask. Say which of the three you used, so an inference about pull requests is never mistaken for one about tasks.

Ground

Now open the repository. Everything above was written without the code in front of anyone, so it is wrong in places nobody can see from the document alone.

Three things only the code answers, and each has a home in the task:

• What the change disturbs. Which existing term changes meaning, and who depends on it today. A status that starts meaning something new breaks every caller branching on it, and none of them appear in the diff of the feature.
• Which decisions are actually one-way. A choice is precedent-setting only relative to what exists. You cannot tell a new pattern from an ordinary one without reading the conventions it will sit beside.
• Where the source is simply wrong. Names the system does not use, APIs that do not exist, a field the document invented. This is the most valuable thing the phase produces, and it goes back to the source, not only into the task.

What you do not settle here is placement. Which folder, which service, how many classes: the repository's own conventions answer most of it and the rest is reversible, so writing it down produces exactly the design document that goes stale and then misleads. Placement is recorded downstream, against the code, by tlc-implement. The exception is a choice that creates a pattern the codebase does not have - that is a one-way door and belongs in Decided like any other.

Walk the surfaces

A surface is anything outside the system that meets it, and each kind carries the same decisions every time it appears. That is what makes a hole findable rather than a matter of remembering: you do not ask "what did I forget about this screen", you walk the row. A thin ticket names the feature and none of these; the walk is what keeps that from shipping as a task with three criteria and an accidental error payload.

| Surface | The decisions it always has | | --- | --- | | a screen or view | empty, loading, error and unauthorised states; density and ordering; what a destructive action confirms before doing it | | an API or webhook someone calls | response shape, error shape with its codes, who may call it, versioning, what happens at the rate limit | | a command or scheduled task | output format and verbosity, every flag and its default, exit codes, what it prints when it fails halfway | | a document or copy someone reads | structure, tone, depth, and what the reader is meant to do next | | a collection being organised | the grouping criterion, naming, ordering, what happens to duplicates, and the exception that does not fit |

Nothing about state, persistence or contracts is here - that is the nine dimensions in Sweep, and duplicating it in both places produces two answers that disagree.

The walk finds gaps. It does not write criteria. Each item resolves to a criterion already in the source or already written from it, to something the code already does (existing - <what>), to n/a - <reason>, or to Unresolved <n>. The n/a escape is mandatory and it is what stops the list from inventing scope: a webhook has no empty state, and saying so costs a line. None - no user-facing surface is a complete answer for a task that exposes none.

A landing that would need a new behaviour is a question, never a numbered line you added so the table looks finished. That is the same refuse-rather-than-guess rule, applied to a list that would otherwise manufacture requirements.

Two of these hide better than the rest. An error shape is decided by whoever writes the first handler, so it gets decided by accident and then copied. An empty state is invisible until the feature ships to someone whose account is new, which is every user on their first day.

Where the record lives: ## Observable in the task, one row per item.

Sweep

The source covers what somebody thought of. The surface walk covers what meets a user. This is the list of what nobody writes down about the system, and it is fixed so that a blank cannot look like nothing to answer: validation, failure modes, idempotency and retry, authorization, concurrency and ordering, data lifecycle, external-dependency failure, state transitions, observability.

Walk all nine, every time, and write where each one landed: a criterion you already wrote, something the code already handles, n/a with the reason, or - when it needs a product answer - Unresolved. Recording the landing is the whole mechanism. A sweep you only think through leaves nothing a reviewer can check, so it decays into a step that gets skipped on the busy day.

Concurrency and observability hide better than the other seven, because neither is visible to a user until it fails. Those two are the reason this list exists.

A landing must be a criterion that observes that dimension. Reaching for a number already used on another line is the tell that the dimension is uncovered: a duplicate rejected because a row already exists says nothing about two requests arriving at once, and a webhook deduplicated by event id says nothing about two webhooks arriving out of order. When you catch yourself borrowing, the honest landings are n/a with the reason, or a question. Both survive being read; a borrowed number does not.

The n/a escape is what stops the list from manufacturing requirements. A dimension that does not apply is a complete answer, and inventing a criterion to fill a row is the failure this would otherwise cause. Growing scope stays the user's call: a dimension that resolves to real new behaviour is a question you ask, never a criterion you add.

tlc-implement reads this instead of sweeping again - a dimension that lands on a criterion here is a check with a proof there.

Refuse rather than guess

Five things must be true of every criterion before you write it:

• someone could observe the outcome - if you cannot say what would be seen, it is too vague
• it carries a concrete value - a status code, a field, a limit; never "gracefully", "properly" or "fast"
• one run settles it - a single execution either satisfies it or does not
• when it claims something will not happen, you can name what prevents it
• the boundary is stated - you can say what is explicitly out

One run has to settle it. This is