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 personal-memory.md); 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:

• --since <arg> if given — a git tag, an ISO date, or Ndays (e.g. --since v1.2, --since 2026-05-01, --since 14days).
• Else, the last brief — ls -t quality_reports/handoffs/*.md | head -1; use the date in its filename as the floor.
• 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.

• 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).
• 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.
• Open plan items — most recent quality_reports/plans/*.md (status + any "Open questions" / "Next" lines) and the latest quality_reports/session_logs/*.md blockers.
• 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.
• 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.

---
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-estimated the event-study with not-yet-treated controls (Callaway–Sant'Anna); main ATT 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 | Notes |
|---|---|---|---|
| Manuscript | `manuscript.tex` | drafting §5 | robustness section is a stub |
| Analysis | `scripts/R/` | replication-ready | passport: 11 PASS, 1 EXPLAINED, 0 FAIL |
| Slides | `Slides/` | current | matches latest results |

## 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 _setup.do`).
3. Run the pipeline: `Rscript scripts/R/00_run_all.R` (or `00_master.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`, open a PR, merge via `/commit`.
- `MEMORY.md` is **committed** — generic learnings sync to everyone.
- `personal-memory.md` and `.claude/state/` stay **local** (gitignored) — 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

• 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).
• 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 the last tag.
• --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/PR/merge is /commit's job.
• 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.