| name | session-walkthrough |
|---|---|
| description | Write a chronological, plain-language walkthrough of technical work — a session recap, a timeline, a "what did we do", a PR or project writeup, a handoff doc — for a reader who knows the product or domain but not the code. Use this whenever someone asks you to summarize, recap, write up, narrate, or document work that was done for a human audience, and especially when that audience is non-engineers, teammates, a manager, or a future reader who wasn't present. Trigger even when they don't say "skill" or name a format: "write up what we did", "timeline of this session", "summarize the work", "explain this PR to my team", "handoff notes", "recap for my boss" all qualify. The point of the skill is style discipline — it exists because ordinary technical summaries drift into jargon and filler that the intended reader can't actually use. |
Produce a walkthrough of work done — what was decided and done, where decisions were overridden or corrected, and what any reviews or checks found — that the intended reader can actually follow and learn from.
The hard part of this task is not recall; it is discipline. Left unchecked, a technical summary drifts into two failure modes: it references code-level concepts as if the reader already knows them, and it pads with sentences that assert importance instead of conveying it. Both make the document useless to the person it's for. Everything below exists to prevent that.
Write for someone familiar with the project at a high level but not with its low-level implementation details — they know the product and the domain, but not this codebase. This is the default and you should not ask about it; a back-and-forth to confirm the audience is exactly the friction this skill is meant to avoid. Just write to that reader.
The one exception: if the person invoking the skill hands you different audience context (a named reader, a different level, "this is for our CEO," "the reader already knows the auth system"), take it and adjust the register accordingly. Use what you're given; don't go fishing for it.
Three threads, woven through the timeline rather than siloed:
- What was decided and done — the actual work, including anything delegated to subagents or tools.
- Where a decision was overridden or corrected — a default that was rejected, a subagent's approach that was changed, a course correction. These are often the most informative moments; don't bury them.
- What reviews, tests, or checks found — the concrete outcomes, including bugs caught and how they were resolved. Structure it chronologically. Phases are a natural fit. Let the structure follow the work; don't impose a template that forces empty sections.
These are the load-bearing part of the skill. Follow them closely — and understand why each one matters, because that lets you apply them to cases these words don't anticipate.
The reader cannot open the code to resolve a term you left dangling, so an undefined term is a dead end for them — the sentence silently stops working. If you name a thing (a rule, a contract, a mechanism, a component, a bug class), the same passage must say what it is, in language the reader already has.
This is the single most common failure. Watch for sentences that would make a knowledgeable-but-outside reader stop and ask "wait, what is that?"
Bad: "It pressure-tested my opening position on the turn-deadline contract." — Three undefined things (the test, the position, the contract) in one sentence. The reader learns nothing.
Good: first state the problem in plain terms — "when the object waits on an external call, its turn can hang, and the platform kills work that runs too long, so there has to be a limit on how long it waits" — then name it as the turn deadline, then say what was decided and why.
"A decision was made about X" carries no information. Give the reader the three things that actually teach: what the earlier position or default was, what it changed to, and the reason. Overrides especially: the interesting content is what was rejected and why, not that an override occurred.
For a bug, a review finding, or a problem, say what actually goes wrong and when — not the kind of problem it is. "A lifecycle issue was found" is a category and tells the reader nothing. "The object could permanently break itself on restart, because the bookkeeping it needed wasn't set up until later" is a failure they can picture.
Explain why something was hard before explaining how it was solved. A solution described before its problem reads as arbitrary; the reader has nothing to hang it on.
"This was worth it," "this is where the value showed," "a rigorous process," "this mattered" — these are the model congratulating the work, not informing the reader. Delete them, or replace them with the specific fact that would let the reader draw that conclusion themselves. If a sentence would survive being deleted with no loss of information, delete it.
Real numbers, real before/after states, the actual failure. "307 tests, up from 303" beats "a comprehensive suite." "Cut the wait from 40 minutes to 90 seconds" beats "much faster."
Referencing a file, component, or tool is fine — but only alongside enough
plain-language explanation that the reader follows the point without opening it.
A bare src/foo/bar.js with no gloss is a reference the reader can't use.
Length should follow the substance. Do not pad to look thorough, and do not compress past the point of clarity — a defined term costs a clause, and that clause is the whole job. A short walkthrough that the reader fully understands beats a long one they can't parse.
A brief, genuine takeaway at the end is fine if it states something the reader would actually want (a pattern, a risk, a next step). A closing line that only praises the work is filler by rule 5 — cut it.
This pass catches what drafting misses. Read the whole thing once as that reader — someone who knows the project but not its internals — and for each sentence ask two questions:
- Could this reader understand it? (Did I leave a term undefined, a reference unglossed, a solution ahead of its problem?)
- Does it tell them something? (Or is it asserting importance, restating the obvious, or padding?) Fix or cut every sentence that fails either test. This step is not optional — it's where the discipline actually lands, because the failure modes are much easier to see in finished prose than to avoid while drafting.