From a67815cdfa6437caef1e306e7fa0cc49f81acc05 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 9 Jun 2026 10:21:07 +0000 Subject: [PATCH 1/8] Add PR agent workflow and instruction docs --- .../chapter-author-agent.md | 21 ++++ .../content-coverage-agent.md | 24 +++++ .../agent-instructions/interactivity-agent.md | 25 +++++ .github/workflows/chapter-pr-agent-cycle.yml | 101 ++++++++++++++++++ docs/agent-workflow.md | 33 ++++++ 5 files changed, 204 insertions(+) create mode 100644 .github/agent-instructions/chapter-author-agent.md create mode 100644 .github/agent-instructions/content-coverage-agent.md create mode 100644 .github/agent-instructions/interactivity-agent.md create mode 100644 .github/workflows/chapter-pr-agent-cycle.yml create mode 100644 docs/agent-workflow.md diff --git a/.github/agent-instructions/chapter-author-agent.md b/.github/agent-instructions/chapter-author-agent.md new file mode 100644 index 0000000..082ec89 --- /dev/null +++ b/.github/agent-instructions/chapter-author-agent.md @@ -0,0 +1,21 @@ +# Chapter Author Agent Instructions + +## Mission +Create or update the chapter notebook from the chapter PDF, open/update the PR, and iterate until review agents report no blocking concerns. + +## Workflow +1. Read chapter PDF and draft notebook structure that follows chapter flow. +2. Add initial explanations, derivations, examples, and exercises. +3. Submit PR with chapter PDF + notebook pair. +4. Wait for review comments from: + - Content Coverage Agent + - Interactivity Agent +5. Apply requested updates with high educational value. +6. Push revisions and re-run review cycle. +7. Repeat until both agents pass. +8. Mark PR ready for human review. + +## Completion gate +Proceed to human review only when: +- No unresolved missing-concept findings from content review. +- No unresolved high-impact interactivity recommendations. diff --git a/.github/agent-instructions/content-coverage-agent.md b/.github/agent-instructions/content-coverage-agent.md new file mode 100644 index 0000000..7fcd512 --- /dev/null +++ b/.github/agent-instructions/content-coverage-agent.md @@ -0,0 +1,24 @@ +# Content Coverage Agent Instructions + +## Mission +Review a chapter PR and verify that notebook content fully covers chapter concepts from the paired PDF. + +## Inputs +- Chapter PDF path from workflow output (`chapter_pdf`) +- Notebook path from workflow output (`chapter_notebook`) +- PR diff + +## Review rules +1. Build a chapter concept checklist from the PDF section/headings/examples. +2. Map each concept to where it appears in the notebook. +3. Flag only **missing** concepts that are present in the chapter but absent in the notebook. +4. Do **not** flag extra material if it is relevant and pedagogically useful. +5. Prioritize mathematically meaningful omissions over formatting/editorial details. + +## Output format for PR comment +- Missing concept: `` + - Why it matters: `` + - Evidence from chapter: `
` + - Suggested notebook placement: `` + +If no meaningful omissions exist, post: `Coverage review passed: all core chapter concepts are present.` diff --git a/.github/agent-instructions/interactivity-agent.md b/.github/agent-instructions/interactivity-agent.md new file mode 100644 index 0000000..a693ec9 --- /dev/null +++ b/.github/agent-instructions/interactivity-agent.md @@ -0,0 +1,25 @@ +# Interactivity Agent Instructions + +## Mission +Review a chapter PR and propose notebook improvements that use visualization and interactivity to improve understanding. + +## Inputs +- Chapter PDF path from workflow output (`chapter_pdf`) +- Notebook path from workflow output (`chapter_notebook`) +- PR diff + +## Review rules +1. Identify concepts in the chapter where plots, sliders, animations, or parameter sweeps would improve comprehension. +2. Propose additions that are concrete and notebook-friendly. +3. Prefer additions tied directly to chapter learning goals. +4. Skip cosmetic-only suggestions unless they directly improve conceptual clarity. +5. Keep recommendations concise and prioritized by educational impact. + +## Output format for PR comment +- Suggested interactive section: `` + - Concept supported: `<concept>` + - Why interactivity helps: `<learning value>` + - Suggested implementation direction: `<plot/widget idea>` + - Suggested location in notebook: `<where to insert>` + +If notebook interactivity is already strong for all major concepts, post: `Interactivity review passed: no high-impact additions identified.` diff --git a/.github/workflows/chapter-pr-agent-cycle.yml b/.github/workflows/chapter-pr-agent-cycle.yml new file mode 100644 index 0000000..99891d3 --- /dev/null +++ b/.github/workflows/chapter-pr-agent-cycle.yml @@ -0,0 +1,101 @@ +name: Chapter PR Agent Cycle + +on: + pull_request: + types: [opened, synchronize, reopened, ready_for_review] + paths: + - "NLPDE/**" + - ".github/agent-instructions/**" + - ".github/workflows/chapter-pr-agent-cycle.yml" + +permissions: + contents: read + pull-requests: write + +jobs: + chapter-context-check: + name: Verify chapter ↔ notebook mapping + runs-on: ubuntu-latest + outputs: + chapter_pdf: ${{ steps.detect.outputs.chapter_pdf }} + chapter_notebook: ${{ steps.detect.outputs.chapter_notebook }} + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Detect changed chapter assets + id: detect + shell: bash + run: | + set -euo pipefail + BASE_SHA="${{ github.event.pull_request.base.sha }}" + HEAD_SHA="${{ github.event.pull_request.head.sha }}" + mapfile -t CHANGED < <(git diff --name-only "$BASE_SHA" "$HEAD_SHA" -- NLPDE) + + PDF=$(printf '%s\n' "${CHANGED[@]}" | grep -E '^NLPDE/.*\.pdf$' | head -n 1 || true) + IPYNB=$(printf '%s\n' "${CHANGED[@]}" | grep -E '^NLPDE/.*\.ipynb$' | head -n 1 || true) + + if [[ -z "$PDF" || -z "$IPYNB" ]]; then + echo "This PR must include both a chapter PDF and its notebook in NLPDE/." + echo "Found PDF: ${PDF:-<none>}" + echo "Found notebook: ${IPYNB:-<none>}" + exit 1 + fi + + PDF_BASE="$(basename "$PDF" .pdf)" + IPYNB_BASE="$(basename "$IPYNB" .ipynb)" + if [[ "$PDF_BASE" != "$IPYNB_BASE" ]]; then + echo "Expected 1:1 chapter naming, but found:" + echo "PDF: $PDF_BASE" + echo "Notebook: $IPYNB_BASE" + exit 1 + fi + + echo "chapter_pdf=$PDF" >> "$GITHUB_OUTPUT" + echo "chapter_notebook=$IPYNB" >> "$GITHUB_OUTPUT" + + content-coverage-agent: + name: Content coverage review + needs: chapter-context-check + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Load content agent instructions + run: cat .github/agent-instructions/content-coverage-agent.md + + - name: Review chapter coverage (placeholder) + run: | + echo "Integrate your preferred PR review agent here." + echo "Context PDF: ${{ needs.chapter-context-check.outputs.chapter_pdf }}" + echo "Context notebook: ${{ needs.chapter-context-check.outputs.chapter_notebook }}" + echo "Goal: report missing concepts from chapter in notebook (extras are allowed)." + + interactivity-agent: + name: Interactivity and visualization review + needs: chapter-context-check + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Load interactivity agent instructions + run: cat .github/agent-instructions/interactivity-agent.md + + - name: Suggest interactive improvements (placeholder) + run: | + echo "Integrate your preferred PR review agent here." + echo "Context PDF: ${{ needs.chapter-context-check.outputs.chapter_pdf }}" + echo "Context notebook: ${{ needs.chapter-context-check.outputs.chapter_notebook }}" + echo "Goal: suggest concrete plot/interactivity additions that improve learning outcomes." + + author-revision-loop: + name: Author agent revision loop guidance + needs: [content-coverage-agent, interactivity-agent] + runs-on: ubuntu-latest + steps: + - name: Load author agent instructions + run: cat .github/agent-instructions/chapter-author-agent.md diff --git a/docs/agent-workflow.md b/docs/agent-workflow.md new file mode 100644 index 0000000..2dac4c0 --- /dev/null +++ b/docs/agent-workflow.md @@ -0,0 +1,33 @@ +# Chapter PR Agent Workflow + +This repository uses a PR-centered multi-agent loop for chapter development in `NLPDE/`. + +## Agents +1. **Chapter Author Agent** + - Creates or updates a chapter notebook from the chapter PDF. + - Opens/updates the PR and applies agent feedback. +2. **Content Coverage Agent** + - Uses the chapter PDF as source-of-truth context. + - Verifies notebook concept coverage and reports missing concepts only. +3. **Interactivity Agent** + - Uses the chapter PDF and notebook to propose high-impact visualization/interactivity additions. + +## PR trigger +Workflow file: `.github/workflows/chapter-pr-agent-cycle.yml` + +On PR updates affecting `NLPDE/**`, the workflow: +- Enforces a 1:1 chapter mapping by requiring matching PDF and notebook base names. +- Runs content coverage review stage. +- Runs interactivity review stage. +- Runs author revision-loop guidance stage. + +## Preprocessing recommendation (shared chapter context) +Yes—preprocessing is recommended because multiple agents reuse the same chapter context. + +Recommended pattern: +1. Extract chapter PDF text once in a preprocessing step. +2. Chunk by section/subsection with page metadata. +3. Create embeddings and index chunks in a vector store. +4. Expose retrieval output to each agent so all reviews use consistent chapter evidence. + +This reduces repeated parsing costs, improves consistency across agent comments, and helps produce page/section-cited feedback. From 02cd9838063d9670e2ae0fd3f1c6acfbfb0978eb Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 9 Jun 2026 10:22:04 +0000 Subject: [PATCH 2/8] Harden chapter workflow validation checks --- .github/workflows/chapter-pr-agent-cycle.yml | 24 ++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/.github/workflows/chapter-pr-agent-cycle.yml b/.github/workflows/chapter-pr-agent-cycle.yml index 99891d3..c6fc141 100644 --- a/.github/workflows/chapter-pr-agent-cycle.yml +++ b/.github/workflows/chapter-pr-agent-cycle.yml @@ -34,8 +34,25 @@ jobs: HEAD_SHA="${{ github.event.pull_request.head.sha }}" mapfile -t CHANGED < <(git diff --name-only "$BASE_SHA" "$HEAD_SHA" -- NLPDE) - PDF=$(printf '%s\n' "${CHANGED[@]}" | grep -E '^NLPDE/.*\.pdf$' | head -n 1 || true) - IPYNB=$(printf '%s\n' "${CHANGED[@]}" | grep -E '^NLPDE/.*\.ipynb$' | head -n 1 || true) + if [[ ${#CHANGED[@]} -eq 0 ]]; then + echo "No NLPDE chapter files changed in this PR update." + exit 1 + fi + + mapfile -t PDF_FILES < <(printf '%s\n' "${CHANGED[@]}" | grep -E '^NLPDE/.*\.pdf$' || true) + mapfile -t IPYNB_FILES < <(printf '%s\n' "${CHANGED[@]}" | grep -E '^NLPDE/.*\.ipynb$' || true) + + if [[ ${#PDF_FILES[@]} -ne 1 || ${#IPYNB_FILES[@]} -ne 1 ]]; then + echo "Expected exactly one chapter PDF and one notebook update." + echo "PDF files found: ${#PDF_FILES[@]}" + printf '%s\n' "${PDF_FILES[@]:-<none>}" + echo "Notebook files found: ${#IPYNB_FILES[@]}" + printf '%s\n' "${IPYNB_FILES[@]:-<none>}" + exit 1 + fi + + PDF="${PDF_FILES[0]}" + IPYNB="${IPYNB_FILES[0]}" if [[ -z "$PDF" || -z "$IPYNB" ]]; then echo "This PR must include both a chapter PDF and its notebook in NLPDE/." @@ -97,5 +114,8 @@ jobs: needs: [content-coverage-agent, interactivity-agent] runs-on: ubuntu-latest steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Load author agent instructions run: cat .github/agent-instructions/chapter-author-agent.md From 0346c48c158303553db10d84074a4301540f1824 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 9 Jun 2026 10:22:55 +0000 Subject: [PATCH 3/8] Wire agent prompts into workflow placeholders --- .github/workflows/chapter-pr-agent-cycle.yml | 31 ++++++++++++++------ 1 file changed, 22 insertions(+), 9 deletions(-) diff --git a/.github/workflows/chapter-pr-agent-cycle.yml b/.github/workflows/chapter-pr-agent-cycle.yml index c6fc141..fbc559f 100644 --- a/.github/workflows/chapter-pr-agent-cycle.yml +++ b/.github/workflows/chapter-pr-agent-cycle.yml @@ -54,13 +54,6 @@ jobs: PDF="${PDF_FILES[0]}" IPYNB="${IPYNB_FILES[0]}" - if [[ -z "$PDF" || -z "$IPYNB" ]]; then - echo "This PR must include both a chapter PDF and its notebook in NLPDE/." - echo "Found PDF: ${PDF:-<none>}" - echo "Found notebook: ${IPYNB:-<none>}" - exit 1 - fi - PDF_BASE="$(basename "$PDF" .pdf)" IPYNB_BASE="$(basename "$IPYNB" .ipynb)" if [[ "$PDF_BASE" != "$IPYNB_BASE" ]]; then @@ -82,14 +75,24 @@ jobs: uses: actions/checkout@v4 - name: Load content agent instructions - run: cat .github/agent-instructions/content-coverage-agent.md + id: content_prompt + shell: bash + run: | + { + echo "prompt<<EOF" + cat .github/agent-instructions/content-coverage-agent.md + echo "EOF" + } >> "$GITHUB_OUTPUT" - name: Review chapter coverage (placeholder) + env: + CONTENT_AGENT_PROMPT: ${{ steps.content_prompt.outputs.prompt }} run: | echo "Integrate your preferred PR review agent here." echo "Context PDF: ${{ needs.chapter-context-check.outputs.chapter_pdf }}" echo "Context notebook: ${{ needs.chapter-context-check.outputs.chapter_notebook }}" echo "Goal: report missing concepts from chapter in notebook (extras are allowed)." + echo "Instruction payload size: ${#CONTENT_AGENT_PROMPT} characters" interactivity-agent: name: Interactivity and visualization review @@ -100,14 +103,24 @@ jobs: uses: actions/checkout@v4 - name: Load interactivity agent instructions - run: cat .github/agent-instructions/interactivity-agent.md + id: interactivity_prompt + shell: bash + run: | + { + echo "prompt<<EOF" + cat .github/agent-instructions/interactivity-agent.md + echo "EOF" + } >> "$GITHUB_OUTPUT" - name: Suggest interactive improvements (placeholder) + env: + INTERACTIVITY_AGENT_PROMPT: ${{ steps.interactivity_prompt.outputs.prompt }} run: | echo "Integrate your preferred PR review agent here." echo "Context PDF: ${{ needs.chapter-context-check.outputs.chapter_pdf }}" echo "Context notebook: ${{ needs.chapter-context-check.outputs.chapter_notebook }}" echo "Goal: suggest concrete plot/interactivity additions that improve learning outcomes." + echo "Instruction payload size: ${#INTERACTIVITY_AGENT_PROMPT} characters" author-revision-loop: name: Author agent revision loop guidance From cdbb5086b9a5cd0abc269993b414c9c594edf679 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 9 Jun 2026 10:24:02 +0000 Subject: [PATCH 4/8] Clarify agent criteria and workflow messages --- .github/agent-instructions/content-coverage-agent.md | 1 + .github/agent-instructions/interactivity-agent.md | 1 + .github/workflows/chapter-pr-agent-cycle.yml | 11 ++++++----- docs/agent-workflow.md | 2 +- 4 files changed, 9 insertions(+), 6 deletions(-) diff --git a/.github/agent-instructions/content-coverage-agent.md b/.github/agent-instructions/content-coverage-agent.md index 7fcd512..f41d34c 100644 --- a/.github/agent-instructions/content-coverage-agent.md +++ b/.github/agent-instructions/content-coverage-agent.md @@ -14,6 +14,7 @@ Review a chapter PR and verify that notebook content fully covers chapter concep 3. Flag only **missing** concepts that are present in the chapter but absent in the notebook. 4. Do **not** flag extra material if it is relevant and pedagogically useful. 5. Prioritize mathematically meaningful omissions over formatting/editorial details. +6. Treat a concept as missing when it has no explicit explanation, derivation, or worked example in the notebook; brief name-only mentions count as insufficient coverage and should be flagged. ## Output format for PR comment - Missing concept: `<name>` diff --git a/.github/agent-instructions/interactivity-agent.md b/.github/agent-instructions/interactivity-agent.md index a693ec9..0e6ccab 100644 --- a/.github/agent-instructions/interactivity-agent.md +++ b/.github/agent-instructions/interactivity-agent.md @@ -14,6 +14,7 @@ Review a chapter PR and propose notebook improvements that use visualization and 3. Prefer additions tied directly to chapter learning goals. 4. Skip cosmetic-only suggestions unless they directly improve conceptual clarity. 5. Keep recommendations concise and prioritized by educational impact. +6. Rank educational impact by: (a) concept difficulty in the chapter, (b) likelihood of student misconceptions, and (c) how strongly interactivity clarifies parameter effects or geometric intuition. ## Output format for PR comment - Suggested interactive section: `<title>` diff --git a/.github/workflows/chapter-pr-agent-cycle.yml b/.github/workflows/chapter-pr-agent-cycle.yml index fbc559f..26a509b 100644 --- a/.github/workflows/chapter-pr-agent-cycle.yml +++ b/.github/workflows/chapter-pr-agent-cycle.yml @@ -35,7 +35,7 @@ jobs: mapfile -t CHANGED < <(git diff --name-only "$BASE_SHA" "$HEAD_SHA" -- NLPDE) if [[ ${#CHANGED[@]} -eq 0 ]]; then - echo "No NLPDE chapter files changed in this PR update." + echo "Failed to detect NLPDE chapter changes; git diff returned no files." exit 1 fi @@ -43,10 +43,10 @@ jobs: mapfile -t IPYNB_FILES < <(printf '%s\n' "${CHANGED[@]}" | grep -E '^NLPDE/.*\.ipynb$' || true) if [[ ${#PDF_FILES[@]} -ne 1 || ${#IPYNB_FILES[@]} -ne 1 ]]; then - echo "Expected exactly one chapter PDF and one notebook update." - echo "PDF files found: ${#PDF_FILES[@]}" + echo "Expected exactly one chapter PDF and one notebook update per PR." + echo "Found ${#PDF_FILES[@]} PDF file(s):" printf '%s\n' "${PDF_FILES[@]:-<none>}" - echo "Notebook files found: ${#IPYNB_FILES[@]}" + echo "Found ${#IPYNB_FILES[@]} notebook file(s):" printf '%s\n' "${IPYNB_FILES[@]:-<none>}" exit 1 fi @@ -60,6 +60,7 @@ jobs: echo "Expected 1:1 chapter naming, but found:" echo "PDF: $PDF_BASE" echo "Notebook: $IPYNB_BASE" + echo "Use matching base names, for example: chapter01.pdf and chapter01.ipynb" exit 1 fi @@ -91,7 +92,7 @@ jobs: echo "Integrate your preferred PR review agent here." echo "Context PDF: ${{ needs.chapter-context-check.outputs.chapter_pdf }}" echo "Context notebook: ${{ needs.chapter-context-check.outputs.chapter_notebook }}" - echo "Goal: report missing concepts from chapter in notebook (extras are allowed)." + echo "Goal: report missing concepts from chapter in notebook (additional relevant material is allowed)." echo "Instruction payload size: ${#CONTENT_AGENT_PROMPT} characters" interactivity-agent: diff --git a/docs/agent-workflow.md b/docs/agent-workflow.md index 2dac4c0..90d670a 100644 --- a/docs/agent-workflow.md +++ b/docs/agent-workflow.md @@ -16,7 +16,7 @@ This repository uses a PR-centered multi-agent loop for chapter development in ` Workflow file: `.github/workflows/chapter-pr-agent-cycle.yml` On PR updates affecting `NLPDE/**`, the workflow: -- Enforces a 1:1 chapter mapping by requiring matching PDF and notebook base names. +- Enforces a 1:1 chapter mapping by requiring exactly one changed PDF and one changed notebook in `NLPDE/`, with identical filenames before the extension (case-sensitive), e.g., `NLPDE/NLPDE_Ch2.pdf` ↔ `NLPDE/NLPDE_Ch2.ipynb`. - Runs content coverage review stage. - Runs interactivity review stage. - Runs author revision-loop guidance stage. From 3c22bf55c49c2cbfa4fc1736f382d3eadc097039 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 9 Jun 2026 10:24:58 +0000 Subject: [PATCH 5/8] Polish workflow error messaging and guidance --- .../agent-instructions/content-coverage-agent.md | 2 +- .github/workflows/chapter-pr-agent-cycle.yml | 16 ++++++++++++---- 2 files changed, 13 insertions(+), 5 deletions(-) diff --git a/.github/agent-instructions/content-coverage-agent.md b/.github/agent-instructions/content-coverage-agent.md index f41d34c..f0e08e7 100644 --- a/.github/agent-instructions/content-coverage-agent.md +++ b/.github/agent-instructions/content-coverage-agent.md @@ -14,7 +14,7 @@ Review a chapter PR and verify that notebook content fully covers chapter concep 3. Flag only **missing** concepts that are present in the chapter but absent in the notebook. 4. Do **not** flag extra material if it is relevant and pedagogically useful. 5. Prioritize mathematically meaningful omissions over formatting/editorial details. -6. Treat a concept as missing when it has no explicit explanation, derivation, or worked example in the notebook; brief name-only mentions count as insufficient coverage and should be flagged. +6. Treat a concept as missing when it has no explicit explanation, derivation, or worked example in the notebook; mentions only in variable names, comments, or section titles without explanatory text count as insufficient coverage and should be flagged. ## Output format for PR comment - Missing concept: `<name>` diff --git a/.github/workflows/chapter-pr-agent-cycle.yml b/.github/workflows/chapter-pr-agent-cycle.yml index 26a509b..7f6c6a5 100644 --- a/.github/workflows/chapter-pr-agent-cycle.yml +++ b/.github/workflows/chapter-pr-agent-cycle.yml @@ -35,7 +35,7 @@ jobs: mapfile -t CHANGED < <(git diff --name-only "$BASE_SHA" "$HEAD_SHA" -- NLPDE) if [[ ${#CHANGED[@]} -eq 0 ]]; then - echo "Failed to detect NLPDE chapter changes; git diff returned no files." + echo "No files changed in NLPDE/, but workflow was triggered by non-NLPDE path filters." exit 1 fi @@ -45,9 +45,17 @@ jobs: if [[ ${#PDF_FILES[@]} -ne 1 || ${#IPYNB_FILES[@]} -ne 1 ]]; then echo "Expected exactly one chapter PDF and one notebook update per PR." echo "Found ${#PDF_FILES[@]} PDF file(s):" - printf '%s\n' "${PDF_FILES[@]:-<none>}" + if [[ ${#PDF_FILES[@]} -eq 0 ]]; then + echo "<none>" + else + printf '%s\n' "${PDF_FILES[@]}" + fi echo "Found ${#IPYNB_FILES[@]} notebook file(s):" - printf '%s\n' "${IPYNB_FILES[@]:-<none>}" + if [[ ${#IPYNB_FILES[@]} -eq 0 ]]; then + echo "<none>" + else + printf '%s\n' "${IPYNB_FILES[@]}" + fi exit 1 fi @@ -60,7 +68,7 @@ jobs: echo "Expected 1:1 chapter naming, but found:" echo "PDF: $PDF_BASE" echo "Notebook: $IPYNB_BASE" - echo "Use matching base names, for example: chapter01.pdf and chapter01.ipynb" + echo "Use matching base names, for example: NLPDE_Ch2.pdf and NLPDE_Ch2.ipynb" exit 1 fi From d2ae0d7ebf6688e0b17e64627930af4b27c33b54 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 9 Jun 2026 10:26:04 +0000 Subject: [PATCH 6/8] Skip chapter jobs for config-only PR updates --- .../content-coverage-agent.md | 3 ++- .github/workflows/chapter-pr-agent-cycle.yml | 23 ++++++++++++++++--- 2 files changed, 22 insertions(+), 4 deletions(-) diff --git a/.github/agent-instructions/content-coverage-agent.md b/.github/agent-instructions/content-coverage-agent.md index f0e08e7..925e6e6 100644 --- a/.github/agent-instructions/content-coverage-agent.md +++ b/.github/agent-instructions/content-coverage-agent.md @@ -14,7 +14,8 @@ Review a chapter PR and verify that notebook content fully covers chapter concep 3. Flag only **missing** concepts that are present in the chapter but absent in the notebook. 4. Do **not** flag extra material if it is relevant and pedagogically useful. 5. Prioritize mathematically meaningful omissions over formatting/editorial details. -6. Treat a concept as missing when it has no explicit explanation, derivation, or worked example in the notebook; mentions only in variable names, comments, or section titles without explanatory text count as insufficient coverage and should be flagged. +6. A concept is considered covered only when the notebook includes explicit explanation, derivation, or a worked example. +7. Mentions only in variable names, comments, or section titles without explanatory text count as insufficient coverage and should be flagged. ## Output format for PR comment - Missing concept: `<name>` diff --git a/.github/workflows/chapter-pr-agent-cycle.yml b/.github/workflows/chapter-pr-agent-cycle.yml index 7f6c6a5..473a761 100644 --- a/.github/workflows/chapter-pr-agent-cycle.yml +++ b/.github/workflows/chapter-pr-agent-cycle.yml @@ -19,6 +19,7 @@ jobs: outputs: chapter_pdf: ${{ steps.detect.outputs.chapter_pdf }} chapter_notebook: ${{ steps.detect.outputs.chapter_notebook }} + skip_review: ${{ steps.detect.outputs.skip_review }} steps: - name: Checkout uses: actions/checkout@v4 @@ -35,9 +36,13 @@ jobs: mapfile -t CHANGED < <(git diff --name-only "$BASE_SHA" "$HEAD_SHA" -- NLPDE) if [[ ${#CHANGED[@]} -eq 0 ]]; then - echo "No files changed in NLPDE/, but workflow was triggered by non-NLPDE path filters." - exit 1 + echo "No files changed in NLPDE/. Workflow triggered by agent instruction or workflow updates only." + echo "skip_review=true" >> "$GITHUB_OUTPUT" + echo "chapter_pdf=" >> "$GITHUB_OUTPUT" + echo "chapter_notebook=" >> "$GITHUB_OUTPUT" + exit 0 fi + echo "skip_review=false" >> "$GITHUB_OUTPUT" mapfile -t PDF_FILES < <(printf '%s\n' "${CHANGED[@]}" | grep -E '^NLPDE/.*\.pdf$' || true) mapfile -t IPYNB_FILES < <(printf '%s\n' "${CHANGED[@]}" | grep -E '^NLPDE/.*\.ipynb$' || true) @@ -78,6 +83,7 @@ jobs: content-coverage-agent: name: Content coverage review needs: chapter-context-check + if: needs.chapter-context-check.outputs.skip_review != 'true' runs-on: ubuntu-latest steps: - name: Checkout @@ -106,6 +112,7 @@ jobs: interactivity-agent: name: Interactivity and visualization review needs: chapter-context-check + if: needs.chapter-context-check.outputs.skip_review != 'true' runs-on: ubuntu-latest steps: - name: Checkout @@ -133,7 +140,8 @@ jobs: author-revision-loop: name: Author agent revision loop guidance - needs: [content-coverage-agent, interactivity-agent] + needs: [chapter-context-check, content-coverage-agent, interactivity-agent] + if: needs.chapter-context-check.outputs.skip_review != 'true' runs-on: ubuntu-latest steps: - name: Checkout @@ -141,3 +149,12 @@ jobs: - name: Load author agent instructions run: cat .github/agent-instructions/chapter-author-agent.md + + config-only-update: + name: Config-only update notice + needs: chapter-context-check + if: needs.chapter-context-check.outputs.skip_review == 'true' + runs-on: ubuntu-latest + steps: + - name: Explain skip + run: echo "Skipping chapter review jobs because no NLPDE chapter files changed." From dd50397ffbbcb82f38e99b30f2299e62d855b09e Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 9 Jun 2026 10:26:56 +0000 Subject: [PATCH 7/8] Improve chapter detection edge-case handling --- .../agent-instructions/content-coverage-agent.md | 2 +- .github/workflows/chapter-pr-agent-cycle.yml | 14 ++++++++++++++ 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/.github/agent-instructions/content-coverage-agent.md b/.github/agent-instructions/content-coverage-agent.md index 925e6e6..c9eea99 100644 --- a/.github/agent-instructions/content-coverage-agent.md +++ b/.github/agent-instructions/content-coverage-agent.md @@ -11,7 +11,7 @@ Review a chapter PR and verify that notebook content fully covers chapter concep ## Review rules 1. Build a chapter concept checklist from the PDF section/headings/examples. 2. Map each concept to where it appears in the notebook. -3. Flag only **missing** concepts that are present in the chapter but absent in the notebook. +3. Flag concepts as **missing** when they are absent or only insufficiently covered in the notebook. 4. Do **not** flag extra material if it is relevant and pedagogically useful. 5. Prioritize mathematically meaningful omissions over formatting/editorial details. 6. A concept is considered covered only when the notebook includes explicit explanation, derivation, or a worked example. diff --git a/.github/workflows/chapter-pr-agent-cycle.yml b/.github/workflows/chapter-pr-agent-cycle.yml index 473a761..a9bd47b 100644 --- a/.github/workflows/chapter-pr-agent-cycle.yml +++ b/.github/workflows/chapter-pr-agent-cycle.yml @@ -31,6 +31,14 @@ jobs: shell: bash run: | set -euo pipefail + if [[ ! -d NLPDE ]]; then + echo "NLPDE directory not found in this checkout; skipping chapter review jobs." + echo "skip_review=true" >> "$GITHUB_OUTPUT" + echo "chapter_pdf=" >> "$GITHUB_OUTPUT" + echo "chapter_notebook=" >> "$GITHUB_OUTPUT" + exit 0 + fi + BASE_SHA="${{ github.event.pull_request.base.sha }}" HEAD_SHA="${{ github.event.pull_request.head.sha }}" mapfile -t CHANGED < <(git diff --name-only "$BASE_SHA" "$HEAD_SHA" -- NLPDE) @@ -47,6 +55,12 @@ jobs: mapfile -t PDF_FILES < <(printf '%s\n' "${CHANGED[@]}" | grep -E '^NLPDE/.*\.pdf$' || true) mapfile -t IPYNB_FILES < <(printf '%s\n' "${CHANGED[@]}" | grep -E '^NLPDE/.*\.ipynb$' || true) + if [[ ${#PDF_FILES[@]} -eq 0 && ${#IPYNB_FILES[@]} -eq 0 ]]; then + echo "No chapter PDF or notebook files found in NLPDE/ changes." + echo "Update the chapter PDF and notebook pair in the same PR." + exit 1 + fi + if [[ ${#PDF_FILES[@]} -ne 1 || ${#IPYNB_FILES[@]} -ne 1 ]]; then echo "Expected exactly one chapter PDF and one notebook update per PR." echo "Found ${#PDF_FILES[@]} PDF file(s):" From a7555c628f33b860f49243ec2d96bf10c196ce1c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 9 Jun 2026 10:27:49 +0000 Subject: [PATCH 8/8] Tighten chapter diff handling and coverage rules --- .github/agent-instructions/content-coverage-agent.md | 1 + .github/workflows/chapter-pr-agent-cycle.yml | 10 +++++++--- 2 files changed, 8 insertions(+), 3 deletions(-) diff --git a/.github/agent-instructions/content-coverage-agent.md b/.github/agent-instructions/content-coverage-agent.md index c9eea99..d34c101 100644 --- a/.github/agent-instructions/content-coverage-agent.md +++ b/.github/agent-instructions/content-coverage-agent.md @@ -16,6 +16,7 @@ Review a chapter PR and verify that notebook content fully covers chapter concep 5. Prioritize mathematically meaningful omissions over formatting/editorial details. 6. A concept is considered covered only when the notebook includes explicit explanation, derivation, or a worked example. 7. Mentions only in variable names, comments, or section titles without explanatory text count as insufficient coverage and should be flagged. +8. Treat insufficient coverage as missing in output comments, and state why the current treatment is not enough for learner understanding. ## Output format for PR comment - Missing concept: `<name>` diff --git a/.github/workflows/chapter-pr-agent-cycle.yml b/.github/workflows/chapter-pr-agent-cycle.yml index a9bd47b..4a0c059 100644 --- a/.github/workflows/chapter-pr-agent-cycle.yml +++ b/.github/workflows/chapter-pr-agent-cycle.yml @@ -41,7 +41,11 @@ jobs: BASE_SHA="${{ github.event.pull_request.base.sha }}" HEAD_SHA="${{ github.event.pull_request.head.sha }}" - mapfile -t CHANGED < <(git diff --name-only "$BASE_SHA" "$HEAD_SHA" -- NLPDE) + DIFF_OUTPUT="$(git diff --name-only "$BASE_SHA" "$HEAD_SHA" -- NLPDE)" || { + echo "Failed to compute NLPDE file diff for base=$BASE_SHA head=$HEAD_SHA." + exit 1 + } + mapfile -t CHANGED <<< "$DIFF_OUTPUT" if [[ ${#CHANGED[@]} -eq 0 ]]; then echo "No files changed in NLPDE/. Workflow triggered by agent instruction or workflow updates only." @@ -52,8 +56,8 @@ jobs: fi echo "skip_review=false" >> "$GITHUB_OUTPUT" - mapfile -t PDF_FILES < <(printf '%s\n' "${CHANGED[@]}" | grep -E '^NLPDE/.*\.pdf$' || true) - mapfile -t IPYNB_FILES < <(printf '%s\n' "${CHANGED[@]}" | grep -E '^NLPDE/.*\.ipynb$' || true) + mapfile -t PDF_FILES < <(printf '%s\n' "${CHANGED[@]}" | grep -E '^NLPDE/[^/]*\.pdf$' || true) + mapfile -t IPYNB_FILES < <(printf '%s\n' "${CHANGED[@]}" | grep -E '^NLPDE/[^/]*\.ipynb$' || true) if [[ ${#PDF_FILES[@]} -eq 0 && ${#IPYNB_FILES[@]} -eq 0 ]]; then echo "No chapter PDF or notebook files found in NLPDE/ changes."