One session for the whole sprint

Use Polygraph to carry context across a feature, from brainstorm to ship, without re-explaining it at every handoff.

A feature moves through brainstorm, spec, implementation, verification, and deploy, often across different people. Each handoff usually leaks context. Someone gets pulled into a Zoom call to catch up, the spec doc is already stale, and "what did we decide about X?" comes up for the third time. A session keeps the full thread (what was tried, what was decided, what was rejected) so the next person picks it up and acts instead of re-deriving it.

Resume or reference

There are two ways to carry context forward, and they're different:

• Resume continues the same session. Your prompts, branches, and PRs all land in it. Use this when you're picking up the same work where someone left off.
• Reference starts a new session with a one-way pointer to the old one. Your agent reads the prior session's context but works on its own branches and timeline. Use this when your part is related but separate, with its own PR.

As a rule of thumb, resume to continue the same task and reference to start your own.

A feature across a sprint

One feature, "personalized search", moving through a cycle and several people.

It starts with the tech lead opening a session to explore the idea:

Add acme/web-app, acme/search-api, acme/ranking-service to this session.

We want to personalize search results. Read the three repos and tell me what
search looks like today, where personalization would plug in, and what we'd
build vs extend. Exploratory, not committing yet.

The next day the lead resumes with polygraph session resume <session-id> and turns that exploration into a spec committed on a branch. The session already holds yesterday's reasoning, so there's nothing to re-explain.

Once the spec is settled, three engineers fan out. Each starts their own session and references the planning one, so their branches stay separate:

Reference Polygraph session <session-id>. Read the spec, then tell me the
slice that applies to search-api. Summarize what I need to build, what's
already been decided, and what I depend on. Don't restate the whole spec.

The agent answers with their slice only, including decisions already made and rejected, so nobody relitigates the cache design that was settled in the planning session.

When the work is done, the lead resumes the original planning session and pulls the three implementation sessions back into it:

Resume the planning session and reference the three implementation sessions
(search-api, ranking-service, web-app).

Compare what shipped against the spec. Which assumptions broke, what did we
learn along the way that we didn't know up front, and where did the
implementation diverge from the plan? Update the spec so it reflects what we
actually built.

The implementation rarely matches the plan exactly. Reconciling it back into the planning session means that one session now holds both the original intent and what really happened, broken assumptions and all. That reconciled session is the retro artifact and the starting point for the next cycle.

Handing off mid-task

When work passes between people on the same session, the outgoing engineer asks the agent to update the session description with what's done, what's next, and what's blocked, then shares the link. The next person resumes and asks:

Summarize where we left off, what's next, and any decision that was made and
rejected so I don't relitigate it.

No spec file to pass, no catch-up call.