/tlc-discover

name: tlc-discover
description: 'Thinks through new or large projects: turns a vague idea into a design doc with a clear product problem and the technical solution. Use when exploring a new project, planning or designing a big project or system, or asked for a "design doc". Do NOT use for clear features or projects (use tlc-spec-lean or tlc-spec-driven).'
license: CC-BY-4.0
metadata:
  author: Tech Leads Club - github.com/tech-leads-club
  version: 0.10.0

TLC Discover

Find out where this project actually is. Understand the problem. Decide whether to solve it. Then, and only then, decide how.

SITUATION ────→ PROBLEM ───────→ VERDICT ───────→ DECIDE
(where this     (no solution     (a stop, or a    (two shapes, costed
 project is)     proposed yet)    record)          against this repo)

**These are not a script, they are the prerequisite order.** What you run is an interview: ask whatever is answerable given what is settled, and stop when nothing answerable is left. The order falls out on its own, because *how* has *whether* as a prerequisite and *whether* has *where we are*. Marching them as four acts is how a discovery asks a project that never shipped what its problem costs today.

The failure that matters here is not inventing a fact, it is **converging early**: proposing a solution on turn two, hearing "sure", and manufacturing a decision that has all the authority of one and none of the examination. Everything below exists to make that harder.

The artifact is a design document that anyone - a person, a team, a planning tool - can plan from without having been in the conversation that produced it. It has to show the design, not only record that one was made: the decisions that are hard to reverse, the flow of the critical path, the states and who moves them, the schema as it will exist, the contracts callers will hold. Where relationship or order is the content, that is a diagram; a table of thirty literals is a spec wearing a design's clothes. And it is organised by vertical slice, so a reader who wants one piece of the work reads one section and finds its diff, its flow, its schema, its contract, its decisions and its open questions there. If the Summary cannot tell a reader what the bet is, a slice cannot show them how its piece moves, or the Slices index which slices are clear, it failed even with every decision recorded.

**The document exists first for people to align on a project, and complete is not the same as readable.** A team reads it in one sitting and has to come out agreeing on what is being built, why, the main rules, the flows, what is hard to reverse and what is still open. Whoever then specifies a feature - a person or an agent - starts from a slice and is expected to read the code, work out the detail and ask questions; the document is the high-level design of a project that will be cut into one or many features, not the spec of any of them. A document that holds every fact and makes a person assemble them - from labels in the skill's own vocabulary, decision numbers they have to look up, and paragraphs carrying five facts each - lost the person. A document that answers every question an implementer could have - every column, every status code, every method touched - lost them too, by being too long to align on, and it will have drifted from the code by the time the feature is specified.

Critical rules

1. **No technology is *proposed* before the verdict.** Not a library, not a provider, not a pattern. If the problem section argues for one, the framing is already a solution. This bans proposing, never knowing: what the project already runs, already committed to and already has half-written is a constraint, and meeting it late is how a discovery reopens what the team closed last month. 2. **The verdict is a stop wherever the decision is open.** Present it and wait. Where Situation established that somebody already committed, it is a line on the record instead of a gate - manufacturing a gate whose answer you know is the approval theatre that teaches everyone to click through the one that mattered. 3. **Never present an option you would not ship.** Two shapes are considered every time; the second earns a section only when it is live. When it is not, it earns one sentence naming what would have to be true for it to win - which is the disqualifying property whoever plans this needs anyway. 4. **Name the number that would change the decision before you go and get it.** Data with no question attached is noise that costs context. And a **missing number is not a finding about the problem** - it is usually a finding about the instrumentation. Ask; never read size out of silence. 5. **A decision without a concrete value is not decided.** A shape, a bound, a status, a field. Everything downstream refuses vague input; catching it here is where it is cheap. 6. **High impact plus low clarity does not get decided here.** It becomes an RFC or a spike. Forcing it produces the most expensive artifact there is: a decision that reads settled and is not. 7. **Solve for this context, not for the reference architecture.** The recommendation is the smallest shape that answers the problem as measured, and anything heavier has to be bought with a condition that is true now or credibly close. Options that exist only to widen the reader's view are welcome and are marked as exactly that - a line each, never dressed as candidates.

The interview

Ask what is answerable now. Every question whose prerequisites are settled is fair; one whose prerequisite is still open is not, because the answer to it is a guess you will then treat as a finding. **You are done when nothing answerable is left**, not when the sections below have all been visited, and a question that matters in a section you have not reached still has to be asked.

**Nothing here is owed a paragraph merely because it exists.** A step with no input costs a line, and a section with no content does not appea