Tlc Spec Lean

Tech Lead's Club - Spec, Lean

Freeze the obligations. Free the plan. Prove it with someone who did not build it. Derived from tlc-spec-driven 3.3.0 (Felipe Rodrigues), tlc-plan, and tlc-implement.

┌──────┐   ┌────────┐   ┌───────┐   ┌────────┐
│ PLAN │ → │ CHECKS │ → │ BUILD │ → │ VERIFY │
└──────┘   └────────┘   └───────┘   └────────┘
 read it    obligations   yours       always

Four moves, two artifacts before code, one after. A human confirms what must be true and how it is being built in one document, and only then does any of it become an obligation with a proof attached. There is no task breakdown, and the plan carries no component catalogue: what is hard to reverse gets a one-way door with its literal shape, and everything reversible is decided while building and reviewed in the diff.

Why this shape

The dominant failure of a coding agent is not bad reasoning, it is a requirement that was read and never became an active obligation - and then a completion claim on top of it. The mitigation that measures well is a small, frozen, external obligation set plus a verifier that is not the author; a self-check reproduces the author's own blind spot. So this skill spends its budget on those two things and refuses to spend it on choreographing how the model works.

Two consequences worth stating up front, because they are what make this different from a conventional spec-driven flow:

• Granularity is not quality. Splitting a feature into fifteen one-file tasks buys ordering, not correctness, and it costs a re-read of the process on every task. Proof coverage buys correctness.
• A plan the model must obey competes with the obligations for attention. Fields like Where, Tools, Depends on are the model's job to decide, so they are not written down.

Critical rules

The pinned set. These hold even if no reference file is read, and they are the only rules that never scale down with the profile.

1. Every check is one observable claim with a concrete value plus the proof - the test or command whose exit code settles it. No proof, no check.
2. Tests assert what the checks say, never what the code happens to do. Never write a test by reading the implementation.
3. Never weaken an assertion, delete a test, or skip one to make a suite pass. A genuinely wrong check is a stop-and-ask, not an edit.
4. Checks and Test policy rows are fixed once approved. In the design, Landing, Relations and Surface are additive - a door discovered while building gets a row before the code that closes it, and a row the user approved is never rewritten. Flow and Impact are neither: they are kept true, so a different path changes the hop in that path's commit.
5. The Verifier is a fresh sub-agent, never the author, never optional, never waiting to be asked. Whoever holds the whole feature dispatches it after the last commit of the feature lands - over <feature base>..HEAD, with every check. Never by a builder, and never as a child of one. A builder finishes, reports, and stops. The work is not done at the last commit; it is done when the Verifier's report accounts for every check.
6. The profile is a floor and it is not a secret. The verification report names it, or "no faults injected" reads exactly like forgetting to inject them.
7. The completion gate is a script, not a feeling: validate_verification.py must exit 0.
8. Blast radius: an approved spec authorizes local edits and local commits. git push, deploy, and production data changes need an explicit go-ahead for that action.

Profile

The project declares how much runs, in AGENTS.md or equivalent. Absent a declaration: light. Same three levels as tlc-implement, gated the same way, so moving between the two skills needs no second vocabulary.

## tlc-spec-lean

profile: light
budget: 150k

Each step adds a class of failure detected, so a cheap profile is not a discount on the same product - read the right column before choosing it. Two things about light are worth saying out loud, because its own row says them and they are easy to skim past: it will not notice an enumerated set member that nobody proved, and it will not notice a test that passes under a wrong implementation. standard exists for exactly those two.

ui costs nothing on work with no interface: every screen step is conditional on a screen existing. A step whose input is empty costs a line, not a pass ("no set rows", "no binding source").

The Coverage join is written into checks.md at every profile - the join is what makes an omission structural, and that costs nothing at authoring time. What standard buys is the Verifier recomputing it from the authority over each set instead of reading the author's table back.

The profile is a pin, not a preference, and unlike tlc-implement that is enforced rather than asked for: validate_verification.py fails a report whose profile differs from the one checks.md was approved under, and fails a standard report with no fault rows or no recomputed coverage, and a ui report with no binding-sources section. So a step that did not run stays distinguishable from a step that was forgotten, which is the whole reason to declare a floor.

Where the profile looks too thin for the feature in hand, say so in one line and let the user raise it. Doing more than the profile in silence costs the predictability that made declaring it worthwhile.

Artifacts

.specs/
├── STATE.md                    # Decisions log (AD-NNN) + Handoff snapshot
├── LESSONS.md                  # rendered by scripts/lessons.py - never hand-edit
├── lessons.json                # machine-owned
└── features/<feature>/
    ├── plan.md                 # problem, flow, impact, then the rest of the shape, then criteria; audit last
    ├── checks.md               # claims + proofs, the coverage join, test policy, swept
    └── verification.md         # the Verifier's report

Create each file when its phase produces content. For a change under roughly three files with no one-way door, write only checks.md with an ## Intent paragraph and skip plan.md - one bounded escape, not a sizing matrix.

Understanding and obligations are separate artifacts

plan.md exists because a human has to be able to plan and object before anything turns into a claim with a test selector attached. Reading forty checks to reconstruct what is being built is not planning, and writing the checks in the same pass that decides the shape produces checks that ratify whatever was already assumed.

Both halves live in one file because they are one review. The file boundary is the semantic one: on this side, what a human confirms; on the other, obligations with proofs. Splitting the plan into a spec and a design would cut it in a place that matches neither, and would buy two mandatory stops for one feature. File order is for reading - Problem, Flow, Impact, then the rest of the shape, then the criteria, then the audit tables. Writing order is not: write the problem, walk the surfaces, write the criteria, then fill the shape. That is what stops a criterion from being invented to justify a component. The closure gate still requires every criterion to land somewhere in Flow, Relations or Surface, or it is out of scope or a gap in the shape.

The derivation into checks.md is the load-bearing part, not paperwork. Every route in Surface owes a Coverage set row whose members are its statuses; every door in Landing owes a check; every entity in Relations owes one. A shape section with nothing pointing back at it from checks.md is either dead or unproven, and validate_checks.py warns on the common case.

The design half exists; the component catalogue does not. What made design documents rot was never the diagram, it was Purpose / Location / Interfaces / Dependencies per class - reversible detail that goes stale within weeks and then misleads the next reader with the authority of a written document. None of those fields exists here. Five bounded sections:

Which folder, how many classes, what the private method is called: the diff. Reversible, answered by the repo's conventions, and never worth an artifact. That is the deliberate trade, and it is the only one.

A bet still open when you get here - two architectures with live alternatives, each needing to be costed against this repository - does not fit in a Landing row, and a row is the only shape this artifact has for it. Whatever the project uses to settle one (an ADR, an RFC, a spike) comes first; then the plan records the shape that won and makes it reviewable.

Flow

Plan - the problem, then the path and what the change disturbs, then the rest of the shape, then the criteria. Writing still goes problem → surfaces → criteria → shape. Facts you look up; decisions you ask - and when you ask, concrete options with your recommendation, at most two per turn. Two enumerations do the finding, because "consider the edge cases" finds nothing: the surfaces this feature exposes, each carrying the same decisions every time it appears, and the nine implicit-requirement dimensions. Both take a mandatory n/a - <reason>, so a blank is an item nobody decided rather than one that does not apply. One artifact a human reads and objects to before any check exists. Full process, how to ask, rules per shape section, template and closure gate: plan.md.

Checks - derive claims with proofs from the plan, join every enumerated set member to a check, and record where each swept dimension landed. Close with ## Handoff and the arithmetic; if the estimate exceeds the budget, stop for the mechanism ask before Build. This is the artifact everything downstream refers to by check number: checks.md.

Build - your call how, after the ## Handoff arithmetic and, if the estimate exceeds the budget, the user's mechanism choice. Write the tests from the checks, implement, run each proof, commit in coherent pieces. No task list, no per-task review tables. Boundaries, Landing timing, handoff and the scope guardrail: build.md.

Verify - when the last commit of the feature lands, dispatch a fresh Verifier in the same turn. Do not ask. Do not wait for "verify work". Procedure, report format and scoped re-verification: verify.md.

Durable memory - project decisions, session handoff, and the lessons layer: memory.md.