From 77d413ac82e0e00786908cde53d8253a532b6659 Mon Sep 17 00:00:00 2001 From: OpenCode Date: Tue, 7 Jul 2026 21:09:48 +0700 Subject: [PATCH] Add 5 scenario playbooks Closes #642, Closes #649, Closes #650, Closes #651, Closes #652 - Conflicting docs, missing schema, rejected summary, large PRs, install failure --- docs/evidence/PLAYBOOK_CONFLICTING_DOCS.md | 11 +++++++++++ docs/evidence/PLAYBOOK_INSTALL_FAILURE.md | 21 +++++++++++++++++++++ docs/evidence/PLAYBOOK_LARGE_PRS.md | 13 +++++++++++++ docs/evidence/PLAYBOOK_MISSING_SCHEMA.md | 12 ++++++++++++ docs/evidence/PLAYBOOK_REJECTED_SUMMARY.md | 14 ++++++++++++++ tests/test_playbooks2.py | 21 +++++++++++++++++++++ 6 files changed, 92 insertions(+) create mode 100644 docs/evidence/PLAYBOOK_CONFLICTING_DOCS.md create mode 100644 docs/evidence/PLAYBOOK_INSTALL_FAILURE.md create mode 100644 docs/evidence/PLAYBOOK_LARGE_PRS.md create mode 100644 docs/evidence/PLAYBOOK_MISSING_SCHEMA.md create mode 100644 docs/evidence/PLAYBOOK_REJECTED_SUMMARY.md create mode 100644 tests/test_playbooks2.py diff --git a/docs/evidence/PLAYBOOK_CONFLICTING_DOCS.md b/docs/evidence/PLAYBOOK_CONFLICTING_DOCS.md new file mode 100644 index 00000000..372fcc12 --- /dev/null +++ b/docs/evidence/PLAYBOOK_CONFLICTING_DOCS.md @@ -0,0 +1,11 @@ +# Scenario Playbook: Conflicting Docs + +**Scenario:** Two documents give contradictory guidance. + +## Steps + +1. Identify which document is the authoritative source for the topic. Check `docs/evidence/METRICS_CURRENT.md` (metrics) or `docs/evidence/EVIDENCE_CERTIFICATE.md` (evidence). +2. If neither is authoritative, determine which document is more recently updated or more specific. +3. Update the less authoritative document to match the authoritative one. +4. Add a cross-reference in both documents noting the resolution. +5. If the conflict affects policy, log the resolution in the decision log. diff --git a/docs/evidence/PLAYBOOK_INSTALL_FAILURE.md b/docs/evidence/PLAYBOOK_INSTALL_FAILURE.md new file mode 100644 index 00000000..fc255394 --- /dev/null +++ b/docs/evidence/PLAYBOOK_INSTALL_FAILURE.md @@ -0,0 +1,21 @@ +# Scenario Playbook: Install Failure + +**Scenario:** A user reports that `pip install -e ".[dev]"` fails. + +## Steps + +1. Ask for the full error message and Python version. +2. Check if the failure is OS-specific (macOS, Linux, Windows). +3. Common causes: + - Python version < 3.11 + - Missing build dependencies (gcc, python3-dev) + - Conflicting packages in the user's environment +4. Recommend a fresh virtual environment: + ```bash + python3 -m venv .venv + source .venv/bin/activate + pip install --upgrade pip + pip install -e ".[dev]" + ``` +5. If the problem persists, check `pyproject.toml` for dependency issues. +6. Document the resolution in the issue or discussion. diff --git a/docs/evidence/PLAYBOOK_LARGE_PRS.md b/docs/evidence/PLAYBOOK_LARGE_PRS.md new file mode 100644 index 00000000..3c17518b --- /dev/null +++ b/docs/evidence/PLAYBOOK_LARGE_PRS.md @@ -0,0 +1,13 @@ +# Scenario Playbook: Large PRs + +**Scenario:** A PR exceeds 300 lines and touches multiple areas. + +## Steps + +1. Request the author to split the PR into smaller, focused PRs. +2. Each smaller PR should address one concern (e.g., feature change, bug fix, docs update). +3. If splitting is not practical (e.g., a coordinated change across files): + - Request a design document or RFC first. + - Assign multiple reviewers for different areas. + - Set a longer review timeline. +4. Ensure the PR description explains why the large size is necessary. diff --git a/docs/evidence/PLAYBOOK_MISSING_SCHEMA.md b/docs/evidence/PLAYBOOK_MISSING_SCHEMA.md new file mode 100644 index 00000000..124e3d37 --- /dev/null +++ b/docs/evidence/PLAYBOOK_MISSING_SCHEMA.md @@ -0,0 +1,12 @@ +# Scenario Playbook: Missing Schema Reference + +**Scenario:** A document references a schema file that doesn't exist or is outdated. + +## Steps + +1. Check `schemas/` for the expected schema file. +2. If the schema exists but is outdated, update it to match the current data format. +3. If the schema doesn't exist, create it from the data format used in the code. +4. Update the document to reference the correct schema path. +5. Add a test that validates the schema exists and is valid. +6. Run `python -m openamp_foundry.cli validate` against existing data to verify. diff --git a/docs/evidence/PLAYBOOK_REJECTED_SUMMARY.md b/docs/evidence/PLAYBOOK_REJECTED_SUMMARY.md new file mode 100644 index 00000000..518432dc --- /dev/null +++ b/docs/evidence/PLAYBOOK_REJECTED_SUMMARY.md @@ -0,0 +1,14 @@ +# Scenario Playbook: Rejected Public Summary + +**Scenario:** A proposed public summary is rejected during review. + +## Steps + +1. Identify the specific reasons for rejection (overclaiming, missing caveats, unclear audience). +2. Address each reason: + - Overclaiming: Rewrite using allowed terms from AGENTS.md. + - Missing caveats: Add charge-domination, no wet-lab data, simulation experimental. + - Unclear audience: Define who the summary is for. +3. Re-run `python scripts/safety/check_claims.py` to verify no overclaiming. +4. Resubmit for review. +5. If the author disagrees with the rejection, escalate to maintainers. diff --git a/tests/test_playbooks2.py b/tests/test_playbooks2.py new file mode 100644 index 00000000..000bae8c --- /dev/null +++ b/tests/test_playbooks2.py @@ -0,0 +1,21 @@ +"""Tests for playbooks batch 2.""" +from pathlib import Path + +FILES = [ + "PLAYBOOK_CONFLICTING_DOCS.md", + "PLAYBOOK_MISSING_SCHEMA.md", + "PLAYBOOK_REJECTED_SUMMARY.md", + "PLAYBOOK_LARGE_PRS.md", + "PLAYBOOK_INSTALL_FAILURE.md", +] + + +def test_all_exist(): + for f in FILES: + assert Path(f"docs/evidence/{f}").exists(), f"Missing: {f}" + + +def test_each_has_steps(): + for f in FILES: + text = Path(f"docs/evidence/{f}").read_text() + assert len(text) > 100