| name | writing-successor-primers |
| description | Writes a "successor primer" — the document a cold-pickup reader needs to carry a non-trivial project forward without the original author present. Covers purpose, founding principles, where-to-start entry points, defense-in-depth false-confidence warnings, project-specific glossary, and an explicit "what's NOT here" list. Use when a project has reached the point where a colleague, a future self, an open-source maintainer, or a next-team member will need to take over without sitting next to the original author. Refuses to write a primer for a throwaway prototype or a project the original author still owns day-to-day; in those cases a README is the right artifact, not a primer.
|
| version | 0.1.0 |
| status | shipped |
| track | workflow |
| audience | ["data-scientist","ml-engineer","security-eng","devops","skill-author"] |
| evidence | ["ATACE","TRACT","ai-security-framework-crosswalk"] |
| last-updated | "2026-05-23T00:00:00.000Z" |
Writing Successor Primers
When to use
Trigger this skill when the user requests or implies one of:
- Handing off a project (planned departure, end of contract, end of rotation, open-sourcing)
- Phrases like "cold pickup", "if you join in six months", "what would my successor need to know?", "transfer doc", "knowledge transfer"
- Mid-stream refactor or rewrite where the original design rationale would otherwise be lost
- A long-running research project (≥ ~3 months) reaching a publication, release, or milestone boundary
- An MLOps / agentic / security system whose layers of redundancy could mislead a successor into trusting the wrong component
When NOT to use
Use a different artifact when:
- The project is a throwaway prototype, a personal scratch repo, or a single-purpose script — a one-paragraph README is the right tool
- The original author still owns the project day-to-day — a README plus inline comments suffice
- The handoff is short-term (a vacation cover, an on-call swap) — a runbook or oncall handoff doc is more appropriate
- The audience is end users, not maintainers — write user docs instead
- The project has no design rationale worth preserving (pure data wrangling, glue scripts) — capture the data lineage in a dataset card and skip the primer
Quick start
User says: "I'm rolling off the incident-rank-validation project at the end of the month. There's no one specific successor — whoever picks this up will probably be a new hire 6 months from now. What do they need?"
Skill response: produces a 1–3 page markdown primer with (1) a 3-sentence purpose statement; (2) the 5–8 founding principles that explain why the project looks the way it looks; (3) a where-to-start list of 3–5 concrete entry points (file paths, run commands, doc reads); (4) a defense-in-depth false-confidence section naming each redundancy layer and the single brittle component it might mask; (5) a glossary of project-specific terms; (6) a "what's NOT here" list of things a reasonable reader might expect but will not find.
Inputs / Arguments / Flags
| Argument | Type | Required | Default | Description |
|---|
| project_root | path | yes | — | Directory whose contents the primer must cover. |
| project_age | string | yes | — | How long the project has existed; under ~3 months → recommend README instead. |
| handoff_kind | "permanent" | "milestone" | "open-source" | yes | — | Permanent and open-source primers need more glossary + false-confidence depth. |
| audience | "engineer" | "researcher" | "executive" | "mixed" | no | "engineer" | Affects vocabulary tier; mixed audiences trigger an executive-summary section. |
| max_length | integer | no | 1500 | Soft word cap; primers longer than 3 pages tend to be ignored. |
Workflow
Copy this checklist into the response and check off items as the primer takes shape:
Primer progress:
- [ ] Purpose written as 3 sentences max
- [ ] Founding principles enumerated (5-8) with WHY each was chosen
- [ ] Where to start: 3-5 entry points (file paths + run commands)
- [ ] Defense-in-depth false-confidence section drafted
- [ ] Project-specific glossary written
- [ ] "What's NOT here" list enumerated
- [ ] Length sanity-check: ≤ ~1500 words / ≤ ~3 pages
- [ ] Primer committed to project root as PRIMER.md or docs/primer.md
Step 1 — Purpose (3 sentences max)
Sentence 1: what the project IS. Sentence 2: who benefits and how. Sentence 3: the one constraint that shapes the design (regulatory, performance, audience).
Step 2 — Founding principles
5–8 numbered principles. Each principle answers "why does the project look like this?" Include the trade-off rejected. Example: "Principle 3: All judges run on Sonnet, not Opus. Trade-off: Opus would score higher on edge cases, but the cost-per-eval is 3× and the eval volume gated a Haiku release; the team accepted slightly noisier scoring to ship monthly."
Step 3 — Where to start
3–5 concrete entry points. Each entry point names a file path, a run command, and a one-sentence outcome. The first entry is "if you read only one thing": the single file that gives the most context per minute.
Step 4 — Defense-in-depth false-confidence
For each layer of redundancy in the system, name what it protects against AND what it would NOT catch. The pattern: "Layer X looks like defense-in-depth for Y, but if Z fails, the layer would not notice." The pattern is critical because layered systems often produce false confidence — a successor who sees three layers may stop investigating, missing the single brittle component all three layers depend on.
Step 5 — Glossary
Project-specific vocabulary: acronyms invented by the team, internal product names, jargon that overloads standard terms. One sentence per entry. Cross-reference any term that appears in the principles or where-to-start sections.
Step 6 — What's NOT here
An explicit list of things a reasonable reader might expect but will not find: feature areas that were descoped, libraries that were evaluated and rejected (with the reason), CI gates that are intentionally absent. This section prevents the successor from re-litigating decisions the original team already made.
Step 7 — Commit + announce
Commit the primer as PRIMER.md (project root) or docs/primer.md. Link from the project's main README. If the handoff has a date, schedule a 30-minute walkthrough on a calendar in the week the primer ships.
Outputs
A markdown document at PRIMER.md (project root) or docs/primer.md, organized as:
- Purpose (3 sentences)
- Founding principles (5–8 numbered with WHY + the rejected trade-off)
- Where to start (3–5 entry points with file path + run command + outcome)
- Defense-in-depth false-confidence warnings (per-layer "looks like X, would not catch Y")
- Glossary (project-specific terms, one sentence each)
- What's NOT here (descoped areas + rejected alternatives + intentional gaps)
- Maintainers + escalation (current owner, escalation contact, project board link if relevant)
- Last updated (date + commit hash)
Target length 800–1500 words; primers longer than ~3 pages are skimmed at best.
Failure modes
Known pitfalls in primer writing and how this skill catches them:
- README disguised as primer (feature list + install steps, no rationale). Caught by: Step 2 requires the WHY + rejected trade-off, which a README never carries.
- Defense-in-depth false confidence omitted (the primer lists redundancies as strengths without naming the brittle dependency). Caught by: Step 4 is a required section, not optional.
- Length bloat (the successor reads the first page and stops). Caught by: 1500-word soft cap + the "if you read only one thing" entry point in Step 3.
- Glossary skipped (the successor hits an acronym in Principle 3 and bounces). Caught by: Step 5 is required; lint suggestion is one entry per acronym that appears in Steps 1–4.
- No "what's NOT here" (successor reopens a closed decision because no record exists). Caught by: Step 6 is required; if the team has no rejected alternatives, the project is probably too young for a primer.
- Stale primer (the project moves on, the primer rots). Mitigated by: Step 8 records last-updated + commit hash, and the project README links to it so drift is visible.
References
Examples
Example 1: Long-running ML project handoff (happy-path)
Input: "I'm rolling off the incident-rank-validation project at the end of the month. There's no one specific successor — whoever picks this up will be a new hire 6 months from now."
Output: a primer with 3-sentence purpose ("Validates the rank-order of AI incidents under 5 severity scorers using NUTS sampler. Used by the IR team to triage incoming reports. Constraint: cross-platform determinism required — CPU-pinned"); 6 founding principles (one of which: "All sampling is CPU-pinned via OMP_NUM_THREADS=1; trade-off: 4× slower than GPU, but cross-platform determinism was the gating requirement for reproducibility"); 4 entry points starting with notebooks/00-orientation.ipynb; defense-in-depth section flagging that the 3 scoring judges look robust but all depend on the same prompt template (single point of brittleness); glossary covering project acronyms; "what's NOT here" listing the GPU acceleration that was tried and rejected.
Example 2: Throwaway prototype (anti-trigger)
Input: "I wrote a quick 80-line script to dedupe a CSV. Want a primer for it?"
Output: skill declines. Explains that a primer is for projects with founding principles worth preserving and successor risk. An 80-line dedupe script needs a docstring at the top of the file and maybe a 3-line README explaining input/output. Hands off to a documentation pattern for scripts.
See also
workflow/writing-release-notes-as-postmortem — pairs naturally; the primer plus a postmortem-style release-note backlog gives a successor history + current-state in two artifactsworkflow/adversarial-premortem-single — produces the defense-in-depth-false-confidence list the primer's Step 4 needsclaude-code-meta/writing-claude-code-skill (planned) — primers for skills follow this same shape
Status & version
- Status: shipped
- Version: 0.1.0
- Last-updated: 2026-05-23
- Provenance: authored 2026-05-23 under PRAGMATIC discipline as part of v2-batch-3 (research-discipline cluster)
