Harness Offboarding

# Harness Offboarding

> Conduct a structured departure debrief for an engineer leaving a harness-managed project. Capture the in-flight context, decisions, and social knowledge they hold in their head, hand off open work and ownership, run an access/knowledge/secret checklist, and verify nothing load-bearing leaves with the person. The symmetric counterpart to harness-onboarding: onboarding gets knowledge _in_, offboarding gets knowledge _out_ before it is lost.

## When to Use

- An engineer (human or agent operator) is leaving a harness-managed project, changing teams, or handing off long-term ownership
- Team shrinkage or reorganization where a person's areas of expertise need a documented successor
- A contractor or temporary contributor is rolling off and their access must be revoked cleanly
- Before extended leave when someone else must carry the person's in-flight work
- When someone asks "how do we hand this off?" or "what do we lose when X leaves?"
- NOT for routine end-of-session handoff between agents (use `summarize_session` / session state directly)
- NOT for archiving or decommissioning a whole project (this is about a _person_ leaving, not the repo ending)
- NOT when the project has no harness configuration (there is no durable surface to write the handoff into — onboard to harness first with harness-initialize-project)

## Process

### Phase 1: CAPTURE — Debrief the In-Flight Context

The goal is to extract what is _only_ in the departing person's head before it walks out the door. Run this as a structured interview, one topic at a time, and record the answers verbatim — do not paraphrase away specifics.

1. **Seed the debrief from durable surfaces first**, so the interview fills gaps rather than re-deriving what is already written:
   - `search_sessions` and `summarize_session` — recent sessions the person drove; surface the decisions and dead-ends already recorded so the interview does not repeat them.
   - `.harness/learnings.md` — what is already captured vs. what the person will say is missing.
   - `.harness/state.json` — the current phase, active task, and any recorded blockers they own.
   - Recent commit and PR authorship (`git log --author`, open PRs) — the surface area they touched most.

2. **Conduct the debrief across the five extraction topics.** Ask about each explicitly; silence on a topic is a gap, not a pass:
   - **Recent decisions made** — choices taken that are not yet written as an ADR (why this library, why this boundary, why this trade-off). These become ADR drafts in Phase 3.
   - **Undocumented gotchas** — the "everyone knows not to touch X on a Friday deploy" tacit knowledge. Fragile sequences, non-obvious ordering, environment quirks.
   - **Conventions held in head** — patterns the person enforced in review that were never written into `AGENTS.md` or a linter (naming, error handling, test structure).
   - **Areas of expertise** — the subsystems where this person was the de-facto owner and who (if anyone) can inherit each.
   - **Known fragile components** — the parts that break in surprising ways, the code nobody else understands, the "here be dragons" map.

3. **Record answers into the handoff artifact scaffold** (written in Phase 3), keeping the person's own words for gotchas and fragility notes — the phrasing carries the warning.

### Phase 2: HANDOFF — Transfer Open Work and Ownership

Move everything the person currently _owns_ to a named successor or an explicit "unowned — needs an owner" state. Nothing may silently remain assigned to someone who is gone.

1. **Reassign roadmap ownership.** Enumerate roadmap rows where the departing person is the `Assignee` (sharded shards under `docs/roadmap.d/`, or `docs/roadmap.md` for monolith projects). For each, either reassign to a successor or mark the assignee empty and flag the row in the handoff artifact as needing an owner. Use `manage_roadmap` (or edit the shard's `- **Assignee:**` line directly for sharded roadmaps — never hand-edit the generated `docs/roadmap.md`).

2. **Hand off in-flight work.** For each open branch, draft PR, or mid-execution plan the person owns:
   - Capture its current state, what is left, and any local-only context (uncommitted intent, review feedback not yet addressed).
   - If `.harness/state.json` shows an active task mid-plan, record where execution stands and what the next task expects, so a successor can resume from `harness state show`.
   - Name the successor per item, or mark it explicitly orphaned for triage.

3. **Transfer expertise ownership.** For each area of expertise from Phase 1, record the successor. Where there is no successor, that is the highest-priority gap for the team to resolve — surface it prominently.

### Phase 3: CHECKLIST — Knowledge, Access, and Secrets

Run the departure checklist. Knowledge items are performed here; access and secret items are _reminders_ the skill surfaces for a human or platform admin to action — the skill never touches credentials itself.

1. **Materialize the handoff artifact.** Write `docs/knowledge/handoff-{person}-{date}.md` containing the captured debrief, the ownership transfer table, and the checklist status. Use the template in "Handoff Artifact Format" below. This is the durable deliverable — unlike onboarding's conversational orientation, offboarding leaves a permanent record.

2. **Generate ADR drafts** from the "recent decisions" captured in Phase 1. Write each as a draft decision record under the project's decisions location (`docs/knowledge/decisions/` or wherever `AGENTS.md` points), marked `status: draft` for a remaining team member to ratify. Do not invent rationale the person did not give.

3. **Ingest into the knowledge graph.** Run `ingest_source` on the new handoff artifact and any ADR drafts so the captured knowledge is queryable via `query_graph` after the person is gone. This is what makes the capture load-bearing rather than a document that rots unread.

4. **Access and secret revocation reminders** (surface as an actionable checklist — the skill does not execute these):
   - Repository and org access (GitHub/GitLab collaborator, team membership, admin rights)
   - CI/CD and deploy credentials, service accounts the person provisioned
   - Cloud console, database, and infrastructure access
   - Secrets the person may know (shared credentials, signing keys, API tokens) — flag for **rotation**, not just revocation, since knowledge of a secret is not revoked by removing access
   - Third-party SaaS seats (monitoring, error tracking, package registries)
   - Personal access tokens or bot tokens tied to the person's account that automation depends on — these must be re-issued under a service identity before revocation, or automation breaks

5. **Knowledge-surface gap review.** Compare the debrief answers against the project's written knowledge surfaces and list what is missing:
   - `AGENTS.md` — conventions the person named that are not documented here
   - `STRATEGY.md` — product/direction context the person held that is not captured
   - `.harness/learnings.md` — gotchas and fragility notes not yet recorded
     Each gap becomes a follow-up item in the handoff artifact.

### Phase 4: VERIFY — Confirm Nothing Is Orphaned

The exit gate. The person should not leave until each of these is closed or explicitly accepted as a known gap.

1. **No orphaned ownership.** No roadmap row still lists the departing person as assignee without either a successor or an explicit "needs owner" flag. Re-scan the roadmap to confirm.

2. **No orphaned in-flight work.** Every open branch/PR/plan the person owned has a named successor or is flagged for triage. Nothing is silently abandoned.

3. **Capture is durable and queryable.** The handoff artifact exists, ADR drafts are written, and `query_graph` can retrieve the ingested handoff — verify with a spot query (e.g., ask the graph for the person's areas of expertise).

4. **Access checklist is acknowledged.** Every revocation/rotation reminder has an owner and a status (done / pending / N/A). Secrets the person knew are flagged for rotation, not just access removal.

5. **Gaps are visible, not hidden.** Any area of expertise with no successor, any undocumented convention, any fragile component with no written warning is listed prominently at the top of the handoff artifact as an accepted risk — so the team decides knowingly rather than discovering it the day it breaks.

## Handoff Artifact Format

Write to `docs/knowledge/handoff-{person}-{date}.md`:

```markdown
# Handoff: <person> — <date>

## Open Risks (read first)

- <area of expertise with no successor>
- <fragile component with no written owner>
- <undocumented convention now at risk>

## In-Flight Work

| Item             | State   | What's Left | Successor            |
| ---------------- | ------- | ----------- | -------------------- |
| <branch/PR/plan> | <state> | <remaining> | <name / NEEDS OWNER> |

## Ownership Transfer

| Area of Expertise | Successor            | Notes     |
| ----------------- | -------------------- | --------- |
| <subsystem>       | <name / NEEDS OWNER> | <context> |

## Decisions Captured (ADR drafts pending)

- <decision> → <adr-draft path> (status: draft)

## Undocumented Gotchas

- <gotcha, in the person's own words>

## Fragile Components

- <component>: <why it's fragile, what breaks it>

## Access & Secret Checklist

| Item            | Action | Owner   | Status  |
| --------------- | ------ | ------- | ------- |
| <repo access>   | revoke | <admin> | pending |
| <shared secret> | rotate | <admin> | pending |

## Knowledge-Surface Gaps

- AGENTS.md: <missing convention>
- STRATEGY.md: <missing context>
- .harness/learnings.md: <missing gotcha>
```

## Harness Integration

- **`search_sessions` / `summarize_session`** — Seed the debrief from the sessions the person drove; recover decisions and dead-ends already recorded.
- **`ingest_source`** — Ingest the handoff artifact and ADR drafts into the knowledge graph so captured knowledge is queryable after departure.
- **`query_graph`** — Verify the capture is durable and retrieve the person's areas of expertise as a completeness check.
- **`manage_roadmap`** — Reassign or unassign roadmap rows the person owned (or edit the shard's `- **Assignee:**` line directly for sharded roadmaps).
- **`harness state show`** — Read `.harness/state.json` to recover the person's active task and blockers for in-flight handoff.
- **`.harness/learnings.md`** — Both a seed (what's captured) and a target (where new gotchas land).
- **`AGENTS.md` / `STRATEGY.md`** — Compared against the debrief to surface undocumented conventions and lost product context.

## Success Criteria

- The five extraction topics were each asked about explicitly (decisions, gotchas, conventions, expertise, fragile components) — no topic silently skipped
- Session history was reviewed via `search_sessions` / `summarize_session` before the interview, so the debrief filled gaps rather than repeating recorded work
- Every roadmap row assigned to the departing person was reassigned or explicitly flagged as needing an owner
- Every open branch, PR, and mid-execution plan the person owned has a named successor or a triage flag
- A durable `docs/knowledge/handoff-{person}-{date}.md` artifact was written with all sections filled
- ADR drafts were generated from the captured decisions and marked `status: draft` (no invented rationale)
- The handoff artifact and ADR drafts were ingested into the knowledge graph and verified retrievable via `query_graph`
- An access/secret checklist was produced, with secrets the person knew flagged for rotation (not just access revocation)
- Knowledge-surface gaps against `AGENTS.md`, `STRATEGY.md`, and `.harness/learnings.md` were enumerated
- Open risks (expertise with no successor, unwarned fragile components) are listed prominently, not buried

## Rationalizations to Reject

| Rationalization                                                                                 | Reality                                                                                                                                                                                                                           |
| ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "They wrote good commit messages, so the context is already captured — I can skip the debrief." | Commit messages record _what_ changed, not the decisions not taken, the gotchas never hit in a commit, or the conventions enforced in review. The tacit knowledge is exactly what commits do not hold.                            |
| "There's no successor for this area, so I'll leave it blank and move on."                       | A blank owner is the single most dangerous outcome of offboarding. An unowned area of expertise must be surfaced as an open risk at the top of the artifact so the team resolves it knowingly — not discovered the day it breaks. |
| "Revoking their repo access covers the secrets too."                                            | Removing access does not un-know a secret. Any shared credential, signing key, or token the person knew must be flagged for rotation. Access revocation and secret rotation are different actions with different owners.          |
| "I'll write the handoff doc but skip graph ingestion — the file is enough."                     | A file nobody queries rots unread. Ingesting into the knowledge graph is what makes the capture retrievable by the next person who asks 'who understood X?' — that is the difference between capture and burial.                  |

## Examples

### Example: Offboarding the De-Facto Owner of a Payments Module

**CAPTURE:**

```
search_sessions(author: "dana") → 3 recent sessions on the payments retry logic
summarize_session → "chose exponential backoff over fixed; idempotency key is (orderId, attempt)"

Debrief:
  - Decisions: "Picked Stripe over Adyen for the EU rollout — Adyen's webhook retry
    semantics didn't match our idempotency model." (no ADR exists)
  - Gotchas: "The reconciliation job MUST run after the settlement window closes at
    23:00 UTC — running it early double-counts refunds."
  - Conventions held in head: "All money is cents-as-integer, never float — enforced
    in review, never linted."
  - Areas of expertise: payments/, the reconciliation cron — no clear successor.
  - Fragile components: "The refund path has a race if two partial refunds land in the
    same second — guarded by a DB unique constraint nobody documented."
```

**HANDOFF:**

```
Roadmap: 2 rows assigned to dana → 1 reassigned to sam, 1 marked NEEDS OWNER
In-flight: branch fix/refund-race → 80% done, review feedback unaddressed → successor sam
State: .harness/state.json shows execute phase, task 3 of 5 on the reconciliation plan
Expertise: payments/ → NEEDS OWNER (surfaced as top open risk)
```

**CHECKLIST + VERIFY:**

```
Wrote docs/knowledge/handoff-dana-2026-08-05.md
ADR draft: docs/knowledge/decisions/stripe-over-adyen.md (status: draft)
ingest_source(handoff-dana-2026-08-05.md) → 1 node, 4 edges
query_graph("dana areas of expertise") → returns payments, reconciliation ✓
Access checklist: repo access (revoke), Stripe dashboard seat (revoke),
  shared Stripe restricted key dana provisioned (ROTATE), CI deploy token (re-issue under service acct)
Gaps: AGENTS.md missing "money is integer-cents"; learnings.md missing reconciliation timing gotcha
Open risk logged: payments/ has no successor
```

### Example: Offboarding a Rolling-Off Contractor

**CAPTURE:**

```
Short-tenure contributor, one subsystem (the CSV import feature).
Debrief:
  - Decisions: none beyond what's in the merged PRs.
  - Gotchas: "The importer assumes UTF-8; latin-1 files silently corrupt — no test covers it."
  - Conventions: followed existing ones, none held in head.
  - Expertise: CSV import only; the full-time team already knows it.
  - Fragile: the encoding assumption above.
```

**HANDOFF + CHECKLIST + VERIFY:**

```
Roadmap: no rows assigned. In-flight: none open.
Wrote docs/knowledge/handoff-jordan-2026-08-05.md (short — most sections "none")
No ADR drafts (no undocumented decisions).
ingest_source → captured the encoding gotcha as a knowledge node.
Access checklist: contractor GitHub collaborator access (revoke), no secrets known (N/A).
Gap: learnings.md missing the UTF-8/latin-1 encoding gotcha → added.
Verify: no orphaned ownership, no orphaned work, gotcha is queryable. Clean exit.
```