1# PR Readiness Runbook
2 
3Use this checklist before an autonomous researcher prepares a PR.
4 
5## Required Artifacts
6 
7- [ ] Source evaluation JSON exists and matches `../templates/source-evaluation.json`.
8- [ ] Skill proposal exists and names the target path.
9- [ ] Skill proposal records novelty-check command, verdict, max mechanism overlap, and top mechanism overlaps.
10- [ ] `validate_run.py --run-dir <run>` passes and `run-state.json` is at `pr_ready` or `closed`.
11- [ ] Mechanism proposals are either promoted, rejected, or explicitly deferred with rationale.
12- [ ] Research thread records discovery, evaluation, and draft decisions.
13- [ ] All cited sources were retrieved successfully.
14- [ ] Rejected or partial sources are recorded as gaps, not cited as evidence.
15- [ ] Human review notes are included when any rubric routes to `HUMAN_REVIEW`.
16 
17## Skill Structure Checks
18 
19- [ ] New or changed `SKILL.md` has YAML frontmatter with `name` and `description`.
20- [ ] Skill directory name matches `name`.
21- [ ] `SKILL.md` is under 500 lines.
22- [ ] Description is third person and describes task boundaries rather than keyword triggers.
23- [ ] Skill contains practical guidance and gotchas.
24- [ ] Volatile evidence is in `references/`, not overloaded into the main skill.
25- [ ] Integration section references related skills by plain name.
26 
27## Sync Checks
28 
29If publishing a new skill, update:
30 
31- [ ] `README.md`
32- [ ] root `SKILL.md`
33- [ ] `.claude-plugin/marketplace.json`
34- [ ] `.plugin/plugin.json` when description or version needs to reflect the new scope
35- [ ] `CLAUDE.md` and `CONTRIBUTING.md` if authoring or packaging rules changed
36 
37## Review Checks
38 
39- [ ] The proposal explains why this is not duplicate content.
40- [ ] The proposal cites accepted mechanisms that overlap and explains why the delta is still needed.
41- [ ] The PR body lists risks and gaps.
42- [ ] The test plan includes deterministic structure checks.
43- [ ] Activation regression cases and researcher benchmarks pass, or failures are listed as risks.
44- [ ] The PR body states that merge requires human approval.
45- [ ] No secrets, credentials, or private source material are included.
46 
47## Stop Conditions
48 
49Stop before PR creation when:
50 
511. Any source was not retrieved but is needed for a claim.
522. A rubric changed during the same run and no independent review occurred.
533. Manifest sync is ambiguous.
544. The draft adds a new skill but activation scenario or mechanism overlaps strongly with an existing one.
555. The user has not approved pushing to GitHub.
56