coauthor-brief

/coauthor-brief — Collaborator Handoff Brief

Produce a single Markdown brief a co-author (or your future self on another machine) can read in a few minutes to know what changed, where each artifact stands, what's blocked, and how to run the pipeline locally — including restricted-data access steps a new collaborator needs. meta-governance.md covers the memory side of cross-machine work (what syncs via git, what stays in gitignored native auto memory); this skill covers the human side: the per-person, per-session handoff.

Core principle: /checkpoint is for you resuming; /coauthor-brief is for someone else starting. The first answers "where am I?"; the second answers "what do I need to know to take over a piece of this?"

When to use

• Before sending a co-author the repo (or a PR / branch) and you want them oriented, not archaeologizing the git log.
• Onboarding a new RA / collaborator who needs the reproduce-locally and restricted-data steps in one place.
• Periodic sync on a long multi-author project — "here's the delta since the last brief."
• Cross-machine handoff — finishing on the office desktop, picking up on the laptop, or handing the analysis half to a co-author who runs Stata while you run R.

When NOT to use

• For your own resume-point — use /checkpoint.
• For distilling a noisy session before auto-compact — use /compress-session.
• For the commit message itself — that goes through /commit.

Phases

Phase 0 — Determine the "since" point

Resolve the delta window, in this priority order:

1. --since <arg> if given — a git tag, an ISO date, or Ndays (e.g. --since v1.2, --since 2026-05-01, --since 14days).
2. Else, the last brief — ls -t quality_reports/handoffs/*.md | head -1; use the date in its filename as the floor.
3. Else, fall back to 14 days and say so in the brief (an unbounded git log is noise, not signal).

Echo the resolved window back before gathering ("Brief covers changes since <tag/date> …").

Phase 1 — Gather the delta + project state

Read-only collection. Skip any source that doesn't apply (R-only, Stata-only, no slides) rather than fabricating.

1. Git delta — git log --oneline --since=<point> (or <tag>..HEAD), git diff --stat <point>..HEAD, git branch --show-current, and git log --all --oneline -15 to see co-authors' parallel branches. Group commits by area (manuscript / analysis / slides / infra).
2. Reproducibility status — if a passport exists at quality_reports/passports/<slug>.yaml, read the PASS / FAIL / EXPLAINED / STALE / UNVERIFIED roll-up (audit-reproducibility, replication-protocol.md). Note whether the analysis is replication-ready or has open FAILs.
3. Open plan items — most recent quality_reports/plans/*.md (status + any "Open questions" / "Next" lines) and the latest quality_reports/session_logs/*.md blockers.
4. Environment / lockfiles — locate the env capture a collaborator needs: renv.lock (R), requirements.txt / environment.yml / uv.lock (Python), a Stata version line + .do ssc install list, or whatever /capture-environment wrote. Record the exact restore command.
5. Restricted-data steps (skip if --no-data-section) — if the repo touches confidential/restricted data, read confidential-data.md and summarize the access path a new collaborator needs (DUA / IRB approval, secure-enclave or openICPSR-restricted credentials, where the data lives, what is git-ignored vs committed). Never copy actual restricted values, paths to live extracts, or credentials into the brief — describe the process to obtain access, not the data.

Phase 2 — Write the brief

Use the template below. Keep it tight (~1–2 screens). Concrete path:line pointers beat prose.

Label every status statement measured or inferred. Measured means a command was run and what you are reporting is its output — name the command. Inferred means you believe it from reading the code, the diff, or a run from some earlier day. Both belong in a brief; mixing them silently does not, because the reader cannot tell which claims they can build on without re-checking. Write replication-ready (measured: Rscript scripts/R/00_run_all.R — 0 FAIL), not replication-ready.

Disposition delegated work item by item. Anything handed to a co-author, an RA, or an agent gets its own line and its own state — done (with the evidence) / in progress / blocked (on what) / not started. "Mostly done" is not a disposition: it hands the reader the job of finding the missing piece, which is precisely the job the brief exists to do.

---
date: YYYY-MM-DD
for: [collaborator name or "all coauthors"]
since: [tag | date | Ndays]
branch: [current branch]
---

# Co-Author Brief — [project / paper short name]

## What changed since [since-point]
[3–8 bullets, grouped by area. Each: what changed + why it matters to a reader, not raw commit subjects.]
- **Analysis:** re-ran the main specification on the de-duplicated sample (533 fanned-out rows dropped); headline estimate now −1.19 — see `scripts/R/03_analyze.R:147`.
- **Manuscript:** Table 2 + §4.2 rewritten to match; Figure 3 regenerated.
- **Slides:** untouched.

## Current state of each artifact
| Artifact | Path | State | Evidence (measured / inferred) |
|---|---|---|---|
| Manuscript | `manuscript.tex` | drafting §5 | inferred — §5 read, not compiled since the Table 2 rewrite |
| Analysis | `scripts/R/` | replication-ready | measured: `Rscript scripts/R/00_run_all.R`, passport 11 PASS / 1 EXPLAINED / 0 FAIL |
| Slides | `Slides/` | current | measured: `git log --since=<point> -- Slides/` returns nothing |

## Delegated work — one line per item
[Everything handed to a co-author, an RA, or an agent, dispositioned individually. No roll-ups.]
| Item | Owner | State | Evidence / blocker |
|---|---|---|---|
| Re-run Table 3 with the new sample filter | [name] | done | measured: output diff vs `output/tab3_prev.csv`, 2 cells moved |
| Appendix B proof of Lemma 2 | [name] | blocked | waiting on the boundedness condition in Q1 below |

## Open questions / decisions needed
[Things the co-author should weigh in on. Mark Q1, Q2…; flag which block progress.]

## Reproduce locally
1. Clone + branch: `git checkout <branch>`
2. Restore environment: `Rscript -e 'renv::restore()'` (or `pip install -r requirements.txt` / Stata `do scripts/stata/00_install.do`).
3. Run the pipeline: `Rscript scripts/R/00_run_all.R` (or Stata `do scripts/stata/99_run_all.do` / `make all`).
4. Verify: `/audit-reproducibility manuscript.tex` should report 0 FAIL.

## Restricted-data access (if applicable)
[Process to obtain access — DUA/IRB/enclave/openICPSR-restricted steps. NO actual data, paths to live extracts, or credentials. See confidential-data.md.]

## Recommended git topology for this project
- One **feature branch per author** (`feat/<author>-<topic>`); rebase on `main`, commit and open a PR with `/commit --pr`, and merge only when the co-authors agree.
- `MEMORY.md` is **committed** — generic learnings sync to everyone.
- Native auto memory (`~/.claude/projects/<project>/memory/`) and `.claude/state/` stay **local** — never expect a co-author to have yours (see meta-governance.md).
- Pull before you brief; brief before you hand off.

Phase 3 — Save and summarize

1. Write to quality_reports/handoffs/YYYY-MM-DD_coauthor-brief.md (create quality_reports/handoffs/ if missing). If --for is set, suffix the slug (…_coauthor-brief_<name>.md).
2. Print to chat: saved path, the resolved since-window, counts (commits summarized / open questions / artifacts), and whether the data section was included or skipped.

Output / report format

A single Markdown handoff doc at quality_reports/handoffs/YYYY-MM-DD_coauthor-brief.md matching the Phase 2 template, plus a one-line chat summary. No edits to any other file.

Exit behavior

• Brief written: exit 0 with the saved path and summary line.
• No "since" resolvable and no git history in window: still write the brief with an explicit "no changes in window" note rather than failing — a co-author starting fresh still needs the state + reproduce + data sections.
• Restricted-data repo detected but confidential-data.md missing: write the brief, leave the data section with a TODO: complete per your DUA placeholder, and warn — do not guess the access process.

Flags

• --since <tag|date|Ndays> — Baseline to diff against — a git tag, an ISO date, or Ndays (e.g. 14days). Default: the previous brief in quality_reports/handoffs/, else 14 days (Phase 0).
• --for <name> — Tailor the brief to a specific collaborator (e.g. surface the restricted-data access steps they still need).

Cross-references

• .claude/rules/meta-governance.md — the cross-machine memory model (what syncs, what stays local) this brief operationalizes for people.
• .claude/skills/capture-environment/SKILL.md — produces the lockfiles the "Reproduce locally" section points at.
• .claude/skills/checkpoint/SKILL.md — the self-resume companion (this skill is the other-person handoff).
• .claude/skills/compress-session/SKILL.md — distil a noisy session before compaction (orthogonal; run before briefing if context is fat).
• .claude/rules/confidential-data.md — restricted-data handling; the data section summarizes its access steps without exposing data.

What this skill does NOT do

• Push, PR, or merge. It writes a doc. Branch, commit and PR are /commit's job; a merge is the user's call.
• Run the pipeline or audit numbers. It reports passport status if one exists; it does not re-run analysis or re-verify claims — that's /audit-reproducibility.
• Capture the environment. It locates and links existing lockfiles; generating them is /capture-environment.
• Expose restricted data. It describes the access process only — never copies confidential values, live data paths, or credentials into a brief that may be emailed or committed.