Record the choices that are settled
docs/DECISIONS.md holds settled choices with dates. That gives a new session somewhere to check before reopening a question. My tech-lead skill tells it not to relitigate those decisions, so the work can continue from the agreement rather than starting the discussion again.
I keep CLAUDE.md for rules every session needs and pointers to the detail. Every session loads that file in full, so filling it with the whole product history would make every job carry the same extra reading. The detailed plan has its own files.
A decision and a task do different work. The decision records the choice; the task describes the change needed to carry it out. Keeping those apart lets me change the order of delivery without making a settled product choice look open again.
Give the queue an order
docs/BACKLOG.md is the ordered queue of PRDs. On withseismic.com, [ ] means open, [~] means shipped up to a seam, and [x] means done and checked live. The status carries a meaning, so an unfinished dependency cannot disappear behind a broad claim of completion.
There is also a Waiting on Doug list and a parking lot. A job needing my decision should be visible as a human ask; an idea we are not taking on belongs outside the active queue. Otherwise both can look like work an agent should quietly continue.
A request that arrives mid-flight becomes a PRD or an edit to one, placed in the queue. The change therefore has a home and a priority. The tech-lead skill moves work I am frustrated about forward instead of leaving it buried in an older conversation.
Describe something a person can observe
Each docs/prds/NN-slug.md holds the goal, locked decisions, acceptance criteria, bounded tasks and dependencies. I write the criteria as observable behaviour: WHEN something happens, the system SHALL behave in a specified way. That gives the builder and checker the same target.
WHEN the page is 375px wide, it SHALL NOT scroll sidewaysThat criterion names the width and the failure. “Make it responsive” would leave both open to interpretation. Use the same approach for the job you know: describe the condition and the result you could actually inspect, rather than an adjective for how it should feel.
Brief the next session by path
The brief explains what and why, points to the files to read, states the boundary and names other work in flight. It also says how to verify the result on the real surface. A builder should be able to find the agreement without asking me to retell it.
Gate commands and things not to do belong there too. They make the limits of the job explicit before work starts. But a detailed brief does not remove review: my tech-lead session still reads the diff, reruns checks and inspects the evidence before treating the result as ready.
My tech-lead skill runs that loop. The agents do most of the typing, while the lead chooses the work, writes the briefs, checks the result and integrates it. The files make that division usable across sessions rather than dependent on who remembers the last conversation.
Write down what reached the visitor
Implementation Notes record what shipped and when it was checked live, including production details. The site’s CHANGELOG.md also describes what changed in terms of what a visitor sees. The changelog comes from a project decision; it is not part of the tech-lead skill itself.
My tech-lead session updates the backlog after the live check, so the queue and the evidence agree. If the work stops at a seam, it records the seam. The next person needs the current truth about the product, including the unfinished part, before deciding what to tackle.