PR Readiness Runbook

Use this checklist before an autonomous researcher prepares a PR.

Required Artifacts

[ ] Source evaluation JSON exists and matches ../templates/source-evaluation.json.
[ ] Skill proposal exists and names the target path.
[ ] Skill proposal records novelty-check command, verdict, max mechanism overlap, and top mechanism overlaps.
[ ] validate_run.py --run-dir <run> passes and run-state.json is at pr_ready or closed.
[ ] Mechanism proposals are either promoted, rejected, or explicitly deferred with rationale.
[ ] Research thread records discovery, evaluation, and draft decisions.
[ ] All cited sources were retrieved successfully.
[ ] Rejected or partial sources are recorded as gaps, not cited as evidence.
[ ] Human review notes are included when any rubric routes to HUMAN_REVIEW.

[ ] New or changed SKILL.md has YAML frontmatter with name and description.
[ ] Skill directory name matches name.
[ ] SKILL.md is under 500 lines.
[ ] Description is third person and describes task boundaries rather than keyword triggers.
[ ] Skill contains practical guidance and gotchas.
[ ] Volatile evidence is in references/, not overloaded into the main skill.
[ ] Integration section references related skills by plain name.

If publishing a new skill, update:

[ ] README.md
[ ] root SKILL.md
[ ] .claude-plugin/marketplace.json
[ ] .plugin/plugin.json when description or version needs to reflect the new scope
[ ] CLAUDE.md and CONTRIBUTING.md if authoring or packaging rules changed

[ ] The proposal explains why this is not duplicate content.
[ ] The proposal cites accepted mechanisms that overlap and explains why the delta is still needed.
[ ] The PR body lists risks and gaps.
[ ] The test plan includes deterministic structure checks.
[ ] Activation regression cases and researcher benchmarks pass, or failures are listed as risks.
[ ] The PR body states that merge requires human approval.
[ ] No secrets, credentials, or private source material are included.

Stop before PR creation when:

Any source was not retrieved but is needed for a claim.
A rubric changed during the same run and no independent review occurred.
Manifest sync is ambiguous.
The draft adds a new skill but activation scenario or mechanism overlaps strongly with an existing one.
The user has not approved pushing to GitHub.

Use this checklist before an autonomous researcher prepares a PR.

[ ] Source evaluation JSON exists and matches ../templates/source-evaluation.json.
[ ] Skill proposal exists and names the target path.
[ ] Skill proposal records novelty-check command, verdict, max mechanism overlap, and top mechanism overlaps.
[ ] validate_run.py --run-dir <run> passes and run-state.json is at pr_ready or closed.
[ ] Mechanism proposals are either promoted, rejected, or explicitly deferred with rationale.
[ ] Research thread records discovery, evaluation, and draft decisions.
[ ] All cited sources were retrieved successfully.
[ ] Rejected or partial sources are recorded as gaps, not cited as evidence.
[ ] Human review notes are included when any rubric routes to HUMAN_REVIEW.

[ ] New or changed SKILL.md has YAML frontmatter with name and description.
[ ] Skill directory name matches name.
[ ] SKILL.md is under 500 lines.
[ ] Description is third person and describes task boundaries rather than keyword triggers.
[ ] Skill contains practical guidance and gotchas.
[ ] Volatile evidence is in references/, not overloaded into the main skill.
[ ] Integration section references related skills by plain name.

If publishing a new skill, update:

[ ] README.md
[ ] root SKILL.md
[ ] .claude-plugin/marketplace.json
[ ] .plugin/plugin.json when description or version needs to reflect the new scope
[ ] CLAUDE.md and CONTRIBUTING.md if authoring or packaging rules changed

[ ] The proposal explains why this is not duplicate content.
[ ] The proposal cites accepted mechanisms that overlap and explains why the delta is still needed.
[ ] The PR body lists risks and gaps.
[ ] The test plan includes deterministic structure checks.
[ ] Activation regression cases and researcher benchmarks pass, or failures are listed as risks.
[ ] The PR body states that merge requires human approval.
[ ] No secrets, credentials, or private source material are included.

Stop before PR creation when:

Any source was not retrieved but is needed for a claim.
A rubric changed during the same run and no independent review occurred.
Manifest sync is ambiguous.
The draft adds a new skill but activation scenario or mechanism overlaps strongly with an existing one.
The user has not approved pushing to GitHub.