---
name: architect-handoff
description: >
  Writes session logs and kickoff documents for any session that changed governance state in
  a deployed instance. Operationalizes the concurrent-session protocol from BOOTSTRAP-BRIEF
  Section IX. Triggered when the operator says: "log this session", "write the handoff",
  "session log", "kickoff for next session", "what did we just do", "wrap this session", "end
  of session writeup", "handoff this work". Refuses trivial sessions (typo fix, one-line
  README) by suggesting the operator just commits with a clear message; insists on session
  logs for any session that changed maturity, made a decision, drained an inbox, or surfaced a
  finding the next operator needs.
---

# architect-handoff

Writes session logs and updates kickoff docs. Operationalizes BOOTSTRAP-BRIEF Section IX (concurrent-session protocol). Refuses trivial sessions; insists on logs for state-changing sessions.

## When to invoke

- Operator says: "log this session", "write the handoff", "session log", "kickoff for next session", "what did we just do", "wrap this session", "end of session writeup"
- End of any session that changed governance state (added or modified a policy, ADR, dossier, kit component); made a decision; drained an inbox; surfaced a finding
- Before context switch when the next operator (future-you, another agent, another team) needs to pick up mid-stream

## Refusal: trivial sessions

If the session was:

- A typo fix in a single document
- A one-line README correction
- A no-op exploration that produced no artifact and no decision
- A trivially-reversible action (e.g., a comment-out and revert)

Suggest the operator just commits with a clear message; do not write a session log. Inflating session-log count dilutes their signal.

## When to write a session log

Write a session log for any session that:

- Changed maturity in any layer (e.g., L4 went from `mature` to `partial`)
- Made a decision worth preserving (whether ADR-worthy or not)
- Drained an inbox or processed an escalation
- Surfaced a finding that the next operator needs
- Took longer than 30 minutes regardless of outcome
- Involved more than one actor (concurrent session)
- Encountered and corrected a named failure mode

## Operating procedure

### Step 1: Establish session scope

Ask (or infer from context):

- What was the session's goal?
- What artifacts changed?
- What decisions were made?
- What was tried and rejected?
- What did the session surface that needs follow-up?

### Step 2: Apply the session-log template

Read `templates/session-log-template.md` for the canonical shape. Populate the sections that have content; explicitly skip ones that don't (with a one-line reason).

Required sections (skip means write "N/A: {reason}"):

- What this session was
- What was produced
- Decisions made
- Findings
- State changes
- Concurrent-actor notes
- Handoff posture
- Failure modes encountered (only if any)
- Session metadata
- Cross-references

### Step 3: File the log

Path: `{instance_root}/sessions/YYYY-MM-DD-{short-purpose}.md`

Naming: kebab-case purpose; date is the session's end date; `short-purpose` should fit in three to five words and reflect the session's primary outcome (e.g., `quarterly-review`, `consent-flow-incident`, `kit-sync-resolution`).

If two session logs would land on the same date with the same purpose token, append `-2` (and so on); collisions are rare but the discipline is to keep paths unique.

### Step 4: Update the kickoff if needed

If the next session needs to pick up mid-stream (work in progress; pending blocker; uncovered finding mid-flight), update the instance's kickoff doc.

The kickoff doc is typically `{instance_root}/OPERATING-MODEL.md`'s "Single highest-leverage next move" section. If the session changes the next-move, update it.

If a more substantive kickoff doc exists (some instances maintain a `KICKOFF.md` for in-flight work), update that.

If the session completed cleanly with no pending work, no kickoff update needed.

### Step 5: Notify other actors if the session has cross-pod consequences

If the session's outcomes affect another pod (e.g., a kit-mirror sync needs a Platform Engineering pair, or a Compliance review is needed):

- Add an outbox entry to the relevant pod's outbox file
- Reference the session log in the outbox entry

If single-pod session with no cross-pod consequences, this step is skipped.

## Quality bar

A good session log lets the next operator pick up cold. Test:

- A capable engineer reads the log without context; can they state what just happened, what's pending, and what to do next?
- Are decisions traceable to rationale (or escalated to ADRs)?
- Are state changes explicit (not "we worked on stuff today")?

If the log fails any of these, revise before filing.

## Cross-references inside the kit

- `BOOTSTRAP-BRIEF.md` Section IX - concurrent-session protocol
- `templates/session-log-template.md` - the canonical shape
- `examples/martech-mature-instance/sessions/` - reference examples (quarterly-review and consent-flow-incident)
- `skills/deploy/SKILL.md` - the deploy skill writes its own first session log; this skill takes over for subsequent sessions
- `skills/architect-adr/SKILL.md` - escalates session-discovered decisions to ADRs when criteria met
- `skills/architect-inbox-flow/SKILL.md` - paired when a session drains an inbox
